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stay In Control Wherever You Go. 



Now, both of these indispensable tools 
are updated to take full advantage of the 
world's most advanced operating system. 


For more than a decade, Ttmbuktu Pro and netOctopus 
have been the leading remote control, file transfer and 
systems administration applications for the Mac OS. 


Mac OS X Ready 


Windows XP Ready 


Timbuktu Pro 

Whether you're at home or at work, Timbuktu Pro allows you to operate distant 
computers as if you were sitting in front of them, transfer files or folders quickly 
and easily, and communicate by instant message, text chat, or voice intercom, 
http: / / www.ti m bu ktu pro.com 


netOctopus 

Intuitive and powerful, netOctopus can manage a network of ten or 10,000 
computers. Inventory computers, software and devices on your network; distribute 
software; configure remote computers: and create custom reports on the fly, 
http: / / www.netoctopus.com 

Learn more, try it, or buy it online. Call us at 1-800-485-5741. 



timbuktu® • netOctopus® 


netopia. 


























YOUR DATABASE SERVER WITH THE 

C-TREE SERVER SDK 



'liHluy’K daUtbasc demands arc often too complex for traditional database servers 
The functionality and precise level of control you need is simply not available. 
Perhaps you need alternate sort criteria for your data or a special twist in the 
threading or communication logic, 

FairConTs c-tree" Server SDK allows you to create a customized, 
industrial-strength server designed for your particular needs. Use 
FairC^>m’s kernel, with over 20 years of proven stability, or override 
functionality within specific subsystems to implement your own 
subtleties. Move your application’s data I/O functions to the 
server-side to decrease network traffic and increase 
performance f 

FairCom’s c-tree Server SDK is used by companies 
worldwide such as Software AG and Citibank*. It’s 
integrated seamlessly into c-tree Plus and includes 
complete source code to the server mainline and all the 
interface subsystems to the entree Server. And 
best of all, once you’ve created your unique, 
customized server, it is easy to install and 
administer: no DBA required! 


* Enhance our server with your own 
custom server-side functionality 

* Move functionality from the client-side to 
the server-side to reduce network tral Hc 
and increase performance 

* Modify or replace entire server 
subsystems 

* Ctimplete source for the server 
mainline, key server 
subsystems, and clienl-sidc 

* Flexible OEM licensing 


Visit www.faircom.cam/ep/mt/sdk today to take control of your server! 


USA 

573.445,6833 

EUROPK 

+39.035,773.464 

^js raircom 

www.faircQm .com 

JAPAN 

+SU59.229.7504 

BRAZIL 

+55 J 13872.9802 

1 OBMe Since 1S7S * 000,634,01 BO 

■ info@^lrcom. 
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Copyright 200S hy Dave Mark 

Getting Started with Cocoa... 


As anyone who knows me well can icll you, I love 
programming? ihc Mac. And 111 play with just about anytliing out 
llicrc that lets me build a Mac app or somehow control the Mac 
interface. When 1 first installed Mac OS X on my laptop, I 
immediately downltwided tlie devcloi>er tools, dug into the doc and 
started building Cocoa applicittions. And immediately got stuck. 

Like a lot of other folks out there, I wa.s a bit (werwlielmed 
with all I needed to learn to truly understand the mechanics of 
Cocoa. For example, I know that I can use Imertace Builder to 
lay out the user interface for an appUcation. But why do I need 
to control-click-drag from one interface clement to another? 
What are outlets? Actions? Targets? What the heck is a File’s 
Owner or a I-irst Responder? 

't hese que.siions are the tip of the iceberg, but common to 
everyone when they first lake on Cocoa. There are a number of 
CtK’oa books out there, some of them quite good, but they all 
make some pretty big leaps in logic - not a big prol>ieni for 
professional developers, but those leaps can leave beginners 
scratching their heads, trying to decide if Cocoa is really hard to 
master or if they are just not up to the task, l^t me assure you - 
Cocoa really is a challenge, even for the experienced developer 

Over the next few months, we re going to dig into CcKoa 
and get the basics down. Build up a deep enough understanding 
of Cocoa mechanics so that all thtrse Ctxrcja txx>ks on your shelf 
make a Itit more sense. 

BKi Nekd Ratscii 

Before we start, I wanted to digress for just a moment, talk 
about a great experience 1 just had. A few weeks ago, Scott 
Knaster and I were fortunate enough to head down to historic 
Banning Mills, about an hour southwest of Atlanta for a week of 
intensive Cocoa training with the folks at Big Nerd Ranch. 

Banning Milis is located on about 700 acres along the 
piciuresque Snake Creek in Carroll County, Georgia. 
Originally home to the Creek and Chemkee nations, in 
the mid-IBOOs it became home to one of the earliest 
textile mills in the south. Over time, a masonry mill was 
built, the mill town grew, wool and cotton yam was 


produced and processed into cloth. Paper and lumf>cT 
products, meal, and flour were also produced. The area 
became an important part of the southern economy. 

Towards the end of the Civil War, General William 
lecumseh Sherman w-as sent to find the mills and destroy 
them. Because of the unique geography of the area (the 
mills are in an extremely well-hidden gorge), he was 
unable to locate the mills and Uiey survived. 

Check out http://historicbanningmills.eom 

I arrived at the ranch on Sunday evening, with the class 
sclieduled u> start Monday morning. Checked into my cabin - 
Ristic with a standalone gas fireplace that really heated up the 
room - not so rustic with Jacuzzi tub, plione, and TV with cable 
as well. Call it "“channing with modern amenities''. Once I 
unpacked, I headed over to the main lodge. To my surprise and 
delight, there was a nice spread of ftxKl laid out, complete with 
a drinks cooler (with all my favorites) and an ice cream freezer 
with alxmi every kind of ice cream you could imagine. And, best 
of all, everyone in the class drifted in and we all sat around tlie 
dining table eating and getting to know (jne another. ScottK kept 
us all enterEamed with war stories from his days at Apple, 
General Magic, and Microsoft. Somehow, each story ended up 
with Scon making friends with a newly minted billionaire. Sadly, 
none of them was me. 

Tlie classes themselves were held in an upstairs meeting 
room at the lodge. Rustic, yei comfortable. A door off of the 
clafNsroom led onto a large deck with a majestic view of Snake 
Creek and the surrounding rocky terrain, At night (and every 
night was a late night) we’d go out onto the deck, talk 
Cocoa, and Lake in a sky full of stars. No light pollution at Big 
Nerd Ranch. 

Our teacher, Aaron Hillega.ss, wa.s exceptional. The class 
was based on an upcoming second edition of his book. 
Cocoa Programming for Mac OSX. The book was presented 
in loose-leaf format. The downside of working from a work- 
in-progres.s is that the code on disk frequently differed from 
the code on the pages. Sometimes the book was right, 


Dave Mark is a long-time Mac developer and author and ha.s written a nuinlier of Ixioks on Macintosh development, including Learn C on the 
Macintosh Imm C++ on the Macintash, and The Macintosh Programming Primer series, interested in Learning Cocoa? Be sure to check out Dave's 
web site at http://www.spiderworkicom. 


GrmNG Started ^tth Cocoa... 


MacTeoi • March 2004 








If a picture is worth a thousand words, 
imagine how priceless a movie would be. 



Snapz Pro X 2.0 allows you to effortlessly record anything on your scret'n^ saving it as a QuickTime® 
movie that can be emailed, iiut up on the web, or passed around however you [:)lease. 



Why take a static scrc^t^nshot when Snapz Pro X 2.0 makes creating a movie just as easy? 
Snapz Pro X 2.0 does that, and so much more — what a difference a version makes! 
Download a free demo version from our web site today and see for yourself: 

http://www.AmbrosiaSW.com/ 



Snapz Pro X 2.0 

AMBROSIA* 

SOFTWARE INC 



Sfiap2 Fro X 


Snapz Pro X, Ambrosia Software, Inc., and the Ambrosia Software logo are registered trademarks of Ambrosia Software, Inc. 









































figure 1. Ihe gmdtmtin^ doss, from kft to RickStode, Bryan iDckumml, Cbrm CampMl ^mii Knmim\ 
Aaron Hiflegass, Dane Mark. Allan Hodtje, Jorge Ramirez, Mark Dahjmtple. and Derek Chan, 

Aaron am the head cheese, and Chrki and Mark bis able assistants. 


,soinL'iin!es llic disk was righl. I typed in all the code and 
fixed any anomalies as I went along, Aaron was terrific about 
answering qii esc ions and helping debug our apps. I liked the 
fact tiiat I typed in the code, as I was sure that 1 understood 
what ultimately ended up working. 

As far as content goes, we covered Objertive-C in detail, 
sf)eiu some time on Xcode, fnterface Builder and the 
Debugger, then got into Cocoa itself. Rather than go over the 
hierarchy cl ass "by-cl ass, Aaron presen red overarching 
concepts, then introduced tlie classes in place as they 
occurred in the code. Kor example, he started by introducing 
a basic user interlace with buttons and a text field, then 
intrc^duced classes like NSControI (and subclasses NSButton, 
NSSlider, NSTextFiekl) and NSAppController. Rather than tour 
through each class, Aaron starred in Interface Builder and 
wared the a[)p together, giving ati overview of each class as it 
was hooked in place. This gave us less of an exhaustive view 
of the class hierarchy and much more a sense of the Cocoa 
design philOsSophy. An excellent approach. 

We ex]>iored Helper Objects, Bindings and NSController 
(and the very important Key-value Coding concept), 
NSUndoManager (holy etjw - it really is easy to add undo to 


your app!). Archiving and the Document Architecture, Nib 
files and NSWindowControllep User Defauks, Noliffications, 
Alert Panels, Localisation, CusLom Views, B vents, 
Responders, Fonts, Pasteboards, Categories, Drag-and-Drop, 
NS'l'inier, Sheets, NSFonnatiers, Printing, Menus, 
NSTextView, building yesur own Interface Builder palettes, 
AppleScript, and OpenGL. 

An amazing amount of material, cnimmed into way too little 
rime. Vet somehow it all worked. I came away remembering 
much of what was taught, but more importantly, i had enough 
resource material to recreate anything I'd forgotten. 

If yoti can afka d it, 1 would strongly recommend Big Nerd 
Ranch. Come prepared, though, as the pace is intense. At the 
very least, before you head out, I w^ould read the dcMiiment 
OhfCpd/m this directory: 

/DevftlDper/DocumentatiQti/Cocoa/Ciineeptual/ObJectiveC/ 

Do your homework first, and I know' you will find the 
experience to he tremendously rewarding. Check out the Big 
Nerd Ranch website at hTtp://wwwhignerdranch.com. You can call 
Lhem at (67K) 59^-677.T 
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IN THE SOPHOS ZONE, VIRUSES NEVER INTERRUPT YOUR WORKFLOW 



I m 

iSf jj ® 


Sophos Anti-Virus provides total protection against all known For a f reef fully supported 

viruses on Mac OS X. Its GU! enables users to perform an evaiuatiorif visit: 

.. . . . , . . , ... www. 50 ptios.com/av mac 

immediate scan of any accessible file, folder and volume, while ^ * 

InterCheck technology keeps users safe by intercepting all file 

accesses and scanning for viruses in the background in real-time. 

In addition, every license includes 24x7x365 technical support. 

In the Sophos Zone, viruses don't stand a chance. 


SOPHOS 


www.sophos.com/avjnac 
Tel 888-216-6703 


engineered for business 

























The Number Generator 

Pcrhiip,s the hesi way lo gvA started wirh Cocoa Ls with a 
simple application that makes use of bodi Interface Builder and 
Xcode, just so you can get a feel for the development process. 
Don't worry about the concepts. Just dick and drag and follow 
along. Over time, the steps you lake in this program will become 
second namre. 

This is the very first project in the upcoming second edition 
of Aaron Hillegass’ Cocoa Programming for Mac OS X. The book 
should hit the stieets in a few' months. 

The program, called RandomApp, puts up a window' with a 
couple of buttons and a text field. One button initializes the 
system's random ntiml>er generator and the second button asks 
the generator to generate a random number between 1 and 100, 
The number is displayed in the text field. The result is shown in 
Figure 2. 


J>J9 0_ Window 



Seed Generator 

) 



Generate Random Number 

) 


42 



Figure 2 RandomApp in action. 



'0:0 0 



New Project 


Empty iVoictl 
YAppjiciiion 

ApdIcScrJpi ApplicArion 
AppleScripf Document-^ased Application 
AppleScript Drppler 
Carbon Application 


Cacoa Document-based Application: 

Cocoa-Java Appl^kaiion 
Cocoa-Java Docvmtrn-based Appiicatioo 
T Bundle 

Carbon Bundk 

Tl^is project builds a Cocoa-based appllcatton written in Ot^enive-C. 


( Cancel ) 


{ Previous ) 


Figure 3. Build a new Cocoa Application projecL 




Next, you1l be prompted to enter a project name and 
project directory (see Figure 4). Name ilie prt>ject RandomApp 
Lind save it in an appropriate directon'. Click the Finish bunon. 

' O0 0 __ ^ Assistant _____ _] 


In thi.s month's installment, well create a project in Xcode, 
then use Imerface Builder to build and Lest the interface. Next 
month, well add the wiring to tie the buttons to the appropriate 
code, then add the code itself. Sounds good? Let's get started, , . 


Create a New Xcode Project 

Launch Xccxle and select New Projeci.. from the Pile 
menu. When prompted, select Cocoa ApplicuHim as the project 
type (see Figure 3). Application is under tlie Application 
section. Be sore you do not select Cixoa Document-based 
Applicaiion, Click the Next button. 

Be sure you have the latest LUid greatest version of the 

developer tools installed. I wrote this column using ^ _ 

Xcode version l.L You can download the Louis at 

http://developer.apple.com. You’ll need to join Apple ^ 

Dewloixm Connection but it Is free to join. Figure 4. Name the project RemdomApp and 

mm it in an appropriate directory. 


Your project window will apj^ear and Xcode will immediately 
begin indexing the project files. Tliis happens in the backgroimd 
and is the reiisoji Xcode’s searches are so incredibly quick, 

I’he left pane of the project window lists the Groups & 
Files that make up the project. One of these groups is named 
NIB Files, Open the NIB Files triangle and you will find the nib 
file for this project, named ManiMenu.nib (see Figure 5) 
Double-ciick on MainMenu.nib to open the nib file in 
Interface Builder. 


hitodibch' 

MAGAZINE 

Get MacTeth delivered to your door at a price FAR BELOW 
the newsstand price. And, it's RISK FREE! 
Subscribe Today! 
vvww.mactech.com 


New Cocoa Application 


Project Wamc: RandomApp 


Project Directory: ^/ Opco ments/Projects/RandomApp/ ^ C Choose... } 

The prciect tllrectorv ^/Docurnents/Pjrpjects/RandotnApp/ i^ttl be created if n«ce»ary. 
and the project file llandamAfip.stcode will be creited therein. 
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Figure?. Ihe RandomApp project windoii\ with 
MainMcmiJiih selected. 


Laying Out the User Interface 

Interface Builder is an incredibly powerful tcx)L It not only 
allows you to design your application’s user interface, it also let’s 
you define the interactions betw'eea the objects that make up 
your applic-^ttion. Mastering the intricacies of connecting objects 
will take time. Wc W'ill definitely spend a lot of time 
experimenting over the months aliead. For now, just follow^ 
along and get RandomApp up and running. You'll get a basic 
sense of the interaction between tnlerface Builder and Xcode, 
and you’ll feel a bit more comft}rtable knowing all your tools are 
in place and working properly. 

When Interface Builder appears, you should see a menu 
window labeled MamMenu.mh- MamMcmu, a window labeled 
Windotv, a main wandow labeled MmnMenu.nib, and a floating 
palette whose name clianges depending on the icon selected 
from the row at the top of the ])alelte. In die palclte window, 
click on the icon with a button and a slider (2^^* from the left, 
as shown in Figure 6) to bring up the c:ontrQls palette, 


© O O Cocoa-Controls C 3 


C 3 iTe:f : r* -j 
C Button } O S ^ 



» 


© Radio 
O Radio 
Q Switch 

[ iteml ~ 






Figure 6. Interface Builders controls palette 


Click on the button in tlie uppcrdefl corner and drag it 
onto the window labeled Window. Take a look at Figure 7. 


Notice that as the button neared Window's upperdeft corner, A 
pair of blue dashed lines appeared. These guide lines tell you 
the item you are dragging is an appropriate distance from the 
nearesi other interface element (in this case, the top and the 
side of the window). This is cjuite a handy way of lining up 
your interface objects. 


Wifujovy 





[ Sutton:^ 


Figure 7. Dragging a button from the palette onto the window. 


Next, click to select the button, then click on the right reside 
bits and drag the rectangle to the right, till the 1)1 tie dashed line 
towards the righi end of the window appear. Now' you should 
have a button that is ahiiost as wide as the window. 

Double-click on the word Button and type Seed Cenemlor, 
followed by a reairn. The button text should change appropriately, 
Now drag out a second button underneath the first one. 
this time, there will be blue guidelines above and to the left of 
the button as you drag tt our. 'lliese guides will keep the 
burton the proper distance from the Lop button and the left side 
of the window. 

Drag the right side of the burron to make it as wide as the 
top button. Doubie-cliek on the word button and change its text 
to say Generate Random Number, 

Figure 8 shows what we have so far... 


..... 


L 

S«fdC«a*riit«r 

. .i 


r 

Cinorac# Randmii Numbw 

) 


A 

Figure 8. Our window vrith turn buttotis. 
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Our next ^tep is to drag our a sialic text field onto llie 
window. In the paletie window, click on the icon in the top 
row (the one that looks like a scrolling text held). I'he palette 
title should change to read Cocoa - Text and a ,serie,s of lexi 
related objects should appear in the palette window. 

Click and drag a static text item from the lower right corner 
of the palette onto the window we are txiikling. Notice that you 
have a choice of several different size static text items. The one 
we want is the largest one and is labeled System Font TexL Just 
as you did with the buttons, drag the text to the left side of the 
window, underneath the 2^^ button. Use die blue guide lines to 
make sure your spacing is ngjit, 

Click and drag on the right side of the text held to resize it 
to the same width as the buttons. 

Next, select Show Info from the Tools menu to bring up a 
boating inspector window. When die Info window appears, click 
on the static text field you just created. The fields t>f the Info 
window will change to reflect the settings of the static text held. 
Change the Title field to die number 0 and click on the centering 
icon in the Alignment: held. Figure 9 shows my settings. 

OOP NSTextField Info 


Finally, click and drag the window to make it shorter. Keep 
it the .same width, though. Figure 10 stiows my hnal window. 


• .0 0 Window 



Test Drive tlie Interface 

Now that your interface is finished, let’s lake it for a spin. 
Select Test Interface from tiie File menu, Tlie RandoinApp 
window should appear, with the title Window and the buttons 
and text as weVe laid them out. 

Tltc hLiitons .sliould l>e oficrable, though they won’t actually 
do anything. When you are done playing, ,seieci 
NewApplication from the Interface Builder menu. This will quit 
the lest drive, not Interface Builder itself. 




Attributes 


Title: 0 
Placeholder: 

Text Color; 
Backgrnd Color: 

Tag: 

Alignment: 

Text Border: 


G Draw 


Vfi 

I 

R 

— 

N 

1 - 0 ' o 




Size: Regular 


Tg 


Layout: O Scrollable 
® Wraps 

Send Action On: 0 Enter only 
End editing 

Options: G Editable 
3 Enabled 
G Selectable 
G Rounded 
Q Hidden 

Figure 9. The info window, showing the changes 
we've made to the NSTextField. 


A 


Tm Next Month... 

In next month’s column, wc'll use Interface builder to 
create a new class specifically designed to seed the ranciom 
number generator and generate a new ranciom numlier. We'll 
create an instance of the class and wire the two buttons to the 
instance's methods tliat seed the generator and generate a new 
numlwr. We'll then go into Xcode and add the code to make the 
application com]i)ete. 

If you dare, lake some lime to play with Interface Builder 
and customiite your interface. Change the window’s title from 
'd/indow to KandomApp. Change the menus. And if you douhle- 
dare, try your hand at finishing tlie jirogram yourself. 

Before you start mucking, thought, please save your 
changes and make a copy of your project directory. Next month, 
we'll want to start exactly where we left off. See you then! © 



GraphicConverter converts 
pictures to different 
formats. Also it contains 
many useful features for 
picture manipulation. 


See wwwJemkesoft.com 

for more information. 
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See Dick. See Dick run his business 
with software that wasn’t written 
and designed for his Macintosh. 

Poor Dick. 


A moment of silence for Dick, please. A good ^ 
guy with a good small business, but his ajccounttng 
software was one of those PC transcription jobs, 
nor pure MAC like MYOB Accounttdge and 
MYOB FtrstEdge. 

If only he'd known about the amazing capacity of MYOB 
software to brirxg out the best in his MAC operating system. 

I Ic could have cracked and managed finances at a glance or generated all the 


reports, invoices, and tax documents that he atid his accountant would 
^ ever need. He could have spent more time with his clients. 


■—' 


'■ vt- t 






Ffn€(S 


L-ETjJ 


li' he had only lotown that MYOB develops the world's 
best selling MAC small business management 
software for lots of good reasons, this story 
might have had a happy ending. Sorry Dick. 

MYOB, 

THE MAC ANSWER. 

CM03 MYOB US. lift, {8«<ima-MYOB www i 


AccoynSEdgo 





































MAC OS X 

PROGRAMMIMC 

SECRETS 


By Scott Knaster 

Your Attention, Please: 
Alerts and Sheets in Cocoa 


I have seen the light, and it turns out to be cocoa-colored. 
As you already know if you have read Dave Mark’s Getting 
Started column, he and 1 spent a transformational week taking 
the Cocoa Booicamp class at the Big Nerd Ranch, During this 
week, the other studenLs and 1 were thrown into an ocean of 
Cocoa, but we didn't drown. Class instructor Aaron Hillegass' 
strategy is to take attendees through an enormous volume of 
material, and it wt>rks: you don't remember everything abf>ut 
everything, but a surprising amount sticks to your i)nun. The 
result is that the class is like a Cocoa Magic Decoder Ring. Now, 
I can look at Cocoa books, documentation, and code, and figure 
out what’s going on - before, 1 couldn't. 

As Dave mentions in his column, the class is held in rural 
Georgia, which is pnjiialily not the first place you think of when 
looking for a hot!>ed of Cocoa development. Rut upon arriving 
at the lodge, I figured oul why this was such a good place for 
Cocoa training: one of the region's legendary characters is Chief 
William McIntosh. His face is all over the lodge, and figore 1 
shows you what he looked like. McIntosh, Cocoa - get 



figure L Chief Wiliiam MclnKkKh is an appropriate historical 
figure in the urea where the Big Nerd Ranch holds its classes. 


In this month’s column, I’m going to start by talking a little 
about some observations and “aha" moments that happen as 
you're trying to figure out what Cocoa is all about. 'I'hen, Til go 
through a gentle example of how you get something done in 
Cocoa: putting up an alert. 

Dkink the Cocoa 

If youTe an old-school programmer with experience writing 
Macintosh or Windows apps, several obstacles pop up 
immediately when you try to learn Cocoa. Tlie roadblocks include: 

• Learning to read and think in Ohjective-C. 

• Learning ro use and trust frameworks in general. 

• Figuring out how to u.se the Cocoa frameworks specifically. 

Learning Objeciive-C is the first challenge to working in 
Cocoa. Although you can use Java with Cocoa, everything is 
designed first with Objective-C in mind. Object!ve-C and 
Cocoa together have some rules and conventions that will 
make you nuLs at first, such as sending messages (which turn 
into method calls) using square brackets, formal parameter 
names (labels) in method calls, using the prefix for lots 
of symbols, including class names, constants, and plain 
functions, and no explicit “override" keyword . You get used 
to most of these, but iheyVe a pain until you get used to 
them. There are also some imponant new concepts lo learn 
when programming in Cocoa with ObjecLivc'C, such as 
delegates (customizing the way objects behave through a 
motlern version of wliat used to be called hooks in the old 
Mac days), categories (a way to add meihod.s and instance 
variables to a cla.ss), and nib files (rite output of Interface 
Builder, consisting of encoded object instances that can l)e 
dect)dcd and used by your running applicaiion). 

If you've programmed with other object-oriented 
Frameworks, you'll lutve an advantage in figuring out Coct>a. 
One t>f the trickiest parts is knowing which piece to use to 
solve a particular problem. The best way to gain this 
knowledge is through experience, which means it's hard when 
you're getting started. 


Scan Knaster attended Qxm IkKJtramp at Big Nerd Ranch (http://www.bignerdranch.com/classes/cocoat.shtml). He did nor go Cocoa Loco but he liked it 
very much. Scott counts die days until pitchers and catchers report. 
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Window 


How can you get around diese obstacles? First, IxJoLstrap 
yourself into Qx'oa with a g<K>d class or book (or both). If you 
like learning by doing, Cocoa Booicamp at the Big Nerd Kanch 
is a fantastic experience. Or, you can read and work through liie 
book Cocoa Program filing for Mac OS X, wliich is basically 
the f>onabk' version of the class. For those who like to learn by 
reading before jumping in and trying things, chec'k out Cocoa 
in a Nutshell. The two btx)ks together form a fine combination. 

As soon as you're to the point where you can look at Cocoa 
code in Objective-C and have a clue about what’s going on, 
make sure you retain and build your skills by writing Cocoa 
code as often as possible. Fresh knowledge tends to evaporate 
if IFs not used. 

Rich Cocoa 

Cocoa provides an amazing box of goodies for 
programmers to play with. Cocoa is so vast that if you printed 
out all the Cocoa APIs and laid them out end to end, you would 
have to walk a very long way indeed to read it all. This month 
and in future editions, well explore cool things you can do in 
Mac OS X using Cocoa, and HI try to make sure we have fun 
while we’re* digging around. Well start out this month with a 
gentle example - putting up an alert “ that will also serve to 
introduce a little of the Cocoa way of doing things. 

Before we write code, lets review a bit of user interface 
lousiness. According to Apple’s Aqua Human Interface Cuidelines, 
Aqua supports tliree kinds of dialogs: modeicss, dcKument modal 
Calst> called sheeLs), and application mrxUil, In this month's column, 
we’re going to work with modal dialogs, which are also called 
alert:!;. Well discuss lx>th document modal and api>lication modal 
alerts. We’ll talk about liow the recomnxended way to create alerts 
has changed recently in Cocoa, and what to do about it. 

Our example app is going to create an alert that lets the 
user confirm whether lo revert to factory settings. What’s being 
reverted, and the adiial reverting itself, are left as exercises for 
you and me lo do laten Our applic-ation will create windows that 
kx)k like Figure 2. The window includes four buttons: two that 
put up application mcxlal dialogs, and two for dcK ument modal 
dialogs (sheets). There are two for each Iwcause we’re 
demonstrating two different techniques for putting up alerts: one 
that was introduced in Mac OS X 10.3, ami one that works in 
previous version,s as well as 10.3^ 


® 0O 


( App Modal (10.2) ) ( Doc Modal (1Q.2) ) 

( App Modal <10.3> ) ( Doc Modal <10.3) ) 

Figure 2 Ihis is what our dix:ummt window will look like. 

It’s Time to Start 

let’s start l)y creating the firoject in Xcode. Choose New 
Project, then Cocoa Document-based Application* Mine is 
named RedAlerr, As usual widi Cocoa projects, we'll start with 
the fun stuff by laying out the user interface and object 
connections in Interface Builder (IB). We double-click 
My Document.nib and IB opens. First, we’ll Iniild the document 
window and the iHiiUms that will appear inside them. Click over 
to ilie Cocoa Windows palette (that's the fourth palette over, 
signified by a tiny picture of a window in the Kxilbar), and drag 
out a window'. ’ITien, click the second tab in the toolbar to go to 
the Controls palette, and drag out four buttons to make your 
window look like the one in Figure 2* 

Now we need a way to make the buitons work. Our big 
plan is lo have the buttons send messages to a controller object 
when the user pushes them. We're going to make a new' class 
called AppController, which will be a suhelas^s of NSObject. Click 
(^^lasses in the MainMenumifj window, then click NSObject. 
Choose Classes ® .Subclass NSObject to make the new class. 
(You can also righK'Jick NSObjed, or simply press return, to 
make a subLlass.) Type a name for die new class: AppControUer. 

NeXT, we have to get App€onirc:)ller objects ready to 
receive messages from the buttons. With AppControIier selected, 
choose Tools ® Show Info, and juake sure Attributes is selected 
on the ]K>puj> menu at the top. We have four different buimns 
that are going to send messages to objects of this class, so well 
define four actions that ctmtrollcr objects can perform. Click Add 
and type in the four actions, one by one: appMt>daiNew, 
appMoclalCJkl, docModalNew, dtK’MrxlalOld. Tim info ins{x:ctor 
should look like the one in Figure 3^ 



Get MacTech delivered to your door at 
a price FAR BELOW the newsstand price. 
And, it's RISK FREE! 

Subscribe Today! 
www.mactech.com 
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Three High-Performance Applications 


Thinkfree Write 

Tliinkfree Write is a powerful word proces3ing application 
that enables you to creote ricK^ professional quality 
documents and Web pages. You can inserJ tables, 
images, and cliport, or even apply custom layouts to 
your document...then effortlessly proofreod your work 
with the easy-to-use spelling and auto-correctfon features. 

Thirrkfree Calc 

Thinkfree Calc ts o full-featured, easy-to-use spreadsheet 
application that can easily tackle the most complex 
anolytical tasks with over 40 charts and 300 function 
capabilities. Thinkfree Calc opens, edits, and saves 
directly into the Microsoft Excel (.xls) format, so users 
can seamlessly share documents and collaborate with 
Microsoft Office users. 

Thinkfree Show 

Thinkfree Show enobles you to create high-impact 
presentations including animation effects, drawings, 
images, clipart, ond other graphic features. Thinkfree 
Show opens, edits and saves directly into the Microsoft 
PowerPoint (.ppt) format. 

C/berdrivePius 

A free, one-year subscription to Cyberdrive PI us is also 
included. Cyberdrive Plus provides you with secure, 

Internet file storage ond free online software upgrades! 
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[ Attiifeutt$ ^ 


Larifuagc: @ Objective-C 

O i 3 ,va View in Editor ^ 

Cla^sNamei AppComroller 


- f 0 Outlets M 4 Acttefif 


Action Nairie 


appModalNew: ^ 

appModalOld: 

docModalNew: 

docModalOld: 

1' 


ftemmrt ( Add ^ 

A 


Figure J. AppC<nUro//er inspector sf?oufs the 
four actions tm created. 


Wc'vc now defined a template for objec ts of llie class 
AppControUer. 'lb actually work with sucli an object here in IR, 
we need to create one. Choose Classes ® Instantiate 
AppController to make an AppComroller object that will l>e 
stored in the nib file. 

Now ifs time to wire this sucker up, IB's famous 
shortcut for connecting one object to another is to hold 
down the Control key while dragging [jciwecn them. We’re 
going to Control-drag from the object that will send the 
mes.sage (in this case, each of the buttons) to the object that 
will perform the action (the AppController). We hold dowm 
Control and start dragging from the first button to the 
MyDocumentmib window, which switches to the Instances 
tab as soon as we drag in, and w'e ki go of the mouse 
button when weVe drawn the line to the AppController 
object. After we connect the two objects, the inspector 
shows the possible actions in AppController that we can 
conned the burton to (sec Figure 4). Pick the appropriate 
action (such as appModalOld for the first button) and 
doul>le-click to make the connection. We repeat this process 
for each of the four buttons. 



!'• *^1. V' 

i_ \ 



figure 4. Connect the hutlons to the AppControUer 
hy Control-dragging in Interface Buikien 


W'e can use the in.specior to tweak the settings of our 
objects. For exam[>le, we can prevent the window from liaving 
a resize box in the lower right corner !>y inspecting it, going to 
the Attrilxites page, and turning off the “Resize’" setting. 

Nt>w weVe bLiili a window with four buttons, created the 
ApjCtJUiroller clas.s. matle an instance of iliat class, and 
connected the buttons to actions in AppController. 'iFie ntb file 
contains all the insiancc.s we built: the window and iLs buttons, 
along with the AppComrolier. Before we leave IB, it will do one 
final favor for ii.s. We go back to tlie jMyDocument.nib window 
and click the Clas.ses tub. Making sure AppComroller is selected, 
we LlKK)se Classes (S) Create Files for AppController. This 
generates skeleton header and implemenlalioii (.h and .m) files 
for our new class and adds them to the project. If only it would 
write all the code for us, we would be done. But for now, we 
still have to do that part ourselves. We’ll bid adieu to our friend 
Interface Builder, .save the nib file, and go over to Xcode. 


XcoDF. Marks the Shh 

In Xcode, w^e're going to ffesh out the four alen-posting 
methods of AppCunlroller that w-e hooked up to the buttons in 
IB. The buttons on the left side of dte window put up 
application mtxial alerts, while the tw^o on the right produce 
cloctiment-modal slieel aleits. Let's talk about the app modal 
alerts first. 

In versions of Mac OS X l>erore 10.3, you put up an app 
modal alert by calling the function NS Run Alert Panel. Note that 
this is a plain old C function caU - no messages sent to objects. 
NSRunAlertPanel takes panimelers that let you specify its text 
and buttons, and returns an integer that indicates which buium 
the user clicked. Here's the full syntax: 


int NSRunAlertPanel (NSString "title. //nunn alert tcxi 
NSString *nisg. // JNXontl line of alert text 
NS S t r i n g * d of atilt But t OH. // right button (usuall)'' OK") 

NSString *alternateButton* //left button (Oon’t ») 

NSSt rlng * otherButtott, // tnitklk buiioo (Oancel) 

,,,) // printr^Jc formatting li>f 3>trtn{i^ 
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You don't have lo pas,s vatucs for ail the pammelcrs - some i>f 
them get default values, ;md others are f>ptk>naL Jf you pass nil for 
defaultBulton, the alert will use tlie lcH:uli;^cd version of "OK” for the 
button lalxd. Hie other buttons are optional - if you pass nil, they 
don't appear. Passing nil for title gets tlie kx-^ali^ed word for “alert". 
Here's the code for putting up the alert using 
NSRunAlertPanel, which works with all versions of Mac OS X: 

- {IBActionJajjpMadalOldi (id) sender 

t 

NSLoj^ t@"sj>pHodfllOld") * 

Int choice = NSUunAlertPancl 
(@'‘0o you want to reveti to factory settings?'", 

@“If you revert to factory aeLtinge, you will lose any cool 
settings of your own that you have made. (10.2 versianr', 
@"Revert‘’, (^"Don*t Revert" ,@"CancGl'"); 

NSLog (#“NSRunAUftPanel returned Xd", choice); 

I 

When you call NSRunAlertPanel, you get some user 
keylx>ard shortcuts (also known as key bindings) autoniatically. 
If the user presses Return or Knier, iltat’s the same as clicking the 
first button. Pressings Rsc is a shortcut for clicking Cancel, If you 
have a butron hihcled "Don’t Save”, the user t:an type Command- 
1) as a shoricut. 

With the advent of Mac OS X 10,3, Cocoa adtled a grcKwy 
new ohjectve way to put up alerts: the <1ass NSAiert. To use 
NSAIert, you create a new aleit object, set it up by semting 
messages to it, then pur it on the screen by calling its runWlodal 
method. Like NSRunAlertPanel (the pre-10.3 function we used 
alKwe), runModaf retunis an integer that tells which button the 
user clicked. Here are some of the NSAIert methcKis youVe likely 
to call when setting up an alert: 

// So ihf ftuin TtTci for the alert 
(void) setK^ssagoText: (NSStrlug * JiaessageTcxt 

// Set the; stvuniiary' the alert 

(void) fietlnformativeTexL: (HSString *)infoText 

// CJuxjse Wamrni;, Info, or t jitieat alert 
(void) iret Al(srtSt,yle: (KSAlertStyle) siylc 

//AckI a burton lo the alert 

(fJSButtoti ‘ ) uddButtonWithTitle: (NSStting *)^Tltle 

Calling addSuttonWithTitle returns the builun. although 
you 11 ofttMi ignore the return value when you’re creating the 
alert. You can call methods on the buttons to tweak their 
appearance ami behavior, Por example, you can call 
setKeyEquivalent to make a keyboard shoricut, or setimage to 
put a cusUHii image on the button. 

When you have the alert built to your specirtcations, you 
send it the runModal messitge and the alert ap[)C'ars. When the 
user dismisses the alert, runModal returns a value that tells you 
which liutton the user clicked- Here's how to pul up the same 
alert as we did before, but using the 10.5 techniciuc with NSAIert; 

[lBA(-rion)nppHo<ielKev: 

I 

NSLog {§"appH(>dalNew"): 

//'Oiis rrtjuiivs ciiuld djeck 

// NSAppKhVVrslonNnmtx:r nc this poini lo l>c suit 


// iCs supporttd. 

// Crt-Mti: till! dtTt obji!ci 

NSAlerl MhoAlftrt ^ (iNSAlert allocl Inlt]; 

// Make lilt buttons. 

// Fi>r casicsl toeaUzution, wc t!t)uld 
// put Uiesi! siring^ in ^ ptwpeny list ^nd 
// read them tti. 

// Huttiin.^ are m!ared from ri^l to k'ft. 
ff 

[theAlert setMessageText you want to ravert to factory 

Bettings?"]: 

ftheAlert EatltiformatlveTextyou revert to factory 
settings, you will lose any cool settings of your own that 
you have made, (10.3 version)"]; 

[theAlert setAleitStyletNSWarningAlartStylel; 

(theAlert addButtanWithTiltet^''Revert”J : 

[thcAlert addButtonWlthTiile:@"Don't Revert"]; 
ftheAlert addButtonWithTitleT^'Xancel"] ; 

// iikJBunonWtrhTitle iiciually renums i!it buium objctl, 

// su you can mess with burtons using tixJc tiki- this: 

// NSbuUun ‘aButton = 

// lUicjUcn addliutionWirhTitk:^'‘Ri!vcn’']; 

// [aButton suiKtybquivaiciii:<^'r"l; 

// [aRuiion j^tlkadSiy k: NS'llik'krffkiuare’BezetSty k |: 

// [aBiitfon setSounU;mySuuniJ I; 

// etc. 

// Put up the akrr and report the dioict 
int choice - ItheAlcrt runModal|: 
switch (choice) 

{ 

case NSAlertFirstButtonHerurn: NSLog 
(@"MSAlertFirstButtonReturn"): break; 

case NSAIertSecondButtonKctoru: MSLog 
(i^MSAiertSecondBurtonRetutn"); break: 

case NSAlottThi rdButtonReturn: NSI.og 
(^"NSAlertThirdButtonRoturn"): break: 

I 

NSl*og {@”MSAlert runHodul; returned choice); 


//'this works tiMj;"compaiihiliiy’ ineUiod 

// Note relumed button vhUk^s are diffmiu (1.0,1 irtsti-ad of lOfK), UMJl. l(Xt2>. 

/* 

LbeAlert = (NSAIert aletiWI thMessageText ;^'‘Dq you want to 
revert to factory setting?* 

defaultBottonje"Revert* 
alternateButton:0"Don‘t Revert* 
otherButton :@"tkince1 ” 

infomtar iveTextWlthFonitat i^i*! r you revert to 
factory settings, you wiTI lose any cool settings of your own 
that you have made, (10,3 version)"): 
choice “ ftheAlert tiinHodal]: 

NSLog (@"NSAlert runModal; returned %d"* choice); 

] 

Muc OS X 10,3 al.'io provides :\ \xMU|>iitibili!y’‘ mcthiid that 
kxykh a lot like the NSRunAlertPanel limcticin. There’s an example 
of it commented out at the Ixtiiom of the la.st listing, Ihis is 
implemented a,s a class method of NSAIert. Here’s its declaration: 

+ (NSAIert *)alertWithMessagcTcxt: (NSString * JmessagcTitle 
defaultEtitton: (NSString* Jdefaul tButtonTltle 
altornatcRutton:(NSString HalrernateButtonTltle 
other ButTon:(NSString*)other&UltonTltie 
informativeTextWIthFormat; (NSString *)fortiiat, , ,, 

Hiere's other cu.stomi 2 :ing you ran do with NSAIert, 
inckiding adduig lielp (sefShowsHelp) liy using a delegate object. 
Check the d(x:umentaiion for NSAIert (and NSButton) to learn 
aliQUt more cool tweaks. 
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Changing ™e Sheets 

Now we're going !o write meilKKls ihni put up doeumeat 
iruKial alerts, also culled sheets. Tliese are ihe cool eye-caady 
dialogs that slip out From window title bars, then roll back in 
when you’re done. As with (nir previous examples, there are^ 
old-school and new-wave ways to do this. We'll show both. 

For ix;sl compatibility with previous and cuiTem versions of 
OS X, use the function NSBeginAlertSheet, defined as follows: 

void NSKeginAlertSheettKSString •rifle. 

MSSLting ‘defaultButton. //denm" llirtT 
NSString ‘alternati^BiiTton, 

NSStrinft •otb^^rBlltrQTl, 

NSUindov ‘doeW t ndow. // wlirIuw tht’ goes with 
id nod 1 Dg 1 c gfi 1 e, // sheet s dek'g^ta* uhjtfct 
SEU d idKndSel tfc Eor, //ifttT iLwr fioLshos 
SEL d idDismlssSelector, f/ catlcd when sheet is g<>ne 
void 'contextlnfo. // passed to its tlar^ 

MSSLring *msg, ...) 


The first few parameters are similar to those we used for 
app niotbl alerts earlier, but diere’s inieresting new stulT too. We 
get to supply pointers to a couple of methods, one that gets 
called when tlie user clicks a bimtm to end the alert, and the 
other that’s summoned after the alert is actually closed. We can 
use these to validate data, record what happened, or for any 
other purpose. The Ibllowing listing shows a barelx^nes example 
of [iow to put up the dtKument iTKKkl alert in our little sample: 

' (IBAction)docHodiitold: (id)sender 
* 

NSU>g te-'docModaiaid"): 

NSBegiiiAIertSheet (^“Do yon watii to revert to tActory 
settings? (10,2 version)", //tide 

§"Don^t Revert" ,#'‘Ganc!el*’. 

[fiondcr uiitidow], // .sender is n humm.We can 
// get its witHlow ihb way 
nil, // clelegaic (owner of next two methiKls) 
nil, //if diis is a methiKl Jielecior, 

// it h caMcd when sheet b done 
nil. // if thb Ls a oiethiH! st'ICctor. 

// it's called when shctl b closed 
nil, // this pointer is passed to die 
// tklegaic when previouii two 
// mciliods are called 
" J: // message tti display In sheet 
// (Note: if tlib is nil we pet 
// a mnimic error.) 

J 

In tiiis example, we’re pa.ssing nil and so skipping the 
chance to use the didEndSeieclor and didDismissSelector 
hooks. If you want lo use eitlicr of these methods, define 
them like this: 

sheetDidEnd:(NSWindow *)sheet 
returnCode:(Int)rcturuGode 
centextinfo:{void *)contextInto; 

sheetDidDisnti ss ; (NSWlndov *) sheet 
rcturnCode: (int) retnrnCode 
contextInfo:(void *)contextInfoi 


When you call NSBeginAlerlSheet, pass a pointer to your 
methods as the appropriate parameter, like ill is: 


@selector{shcGthidEnd:returnCodeiContextlnfo;) nnd 
@fjelector {ijlieetDidDlsmles: retumCode: context Info:) 

CtR*oa will call your sheetDidEnd melluKl when the user 
finishes widi the sheet, and the sheet Did Dismiss methtxl after the 
sheet is actually gone. You can arrange to pass anything y<ju 
wanl in ihe contextlnfo parameter. 

Just as with app modal alerts, the freshest Mac OS X 10,3 
Cocoa prt)vides the NSAIert tTa,ss for you to create diR'umtmr 
mfKlal alerts. You use it by sending me,ssages to build an NSAIert 
object, tlicn sending another message to actually show the alert. 
Here's the relevant code from our sample app: 

- (IBActipnldQcModsiKGv: (Id)sGndGr 
I 

N S Log (§"d ocHod a1N p w"J; 

NSAIert •thnAlGrt = [[[NSAIert alloc] Ifiitl aiitnrelcase] i 
// set up huiKms 

[theAlori addButtQnWithTltlc:@"Revert"] : 

[tBoAlort add]3uttonWithTitle:e"€ancn1") i 

[thoAlert addButtonWithTltlR:@"Don'l Revert"J: 

// set up icxi 

ItheAlert setHe,^f!agoTcxt :e"ao you want to revert to factory 
settings?”]: 

ItheAlert sctlnfotmijtivetext:§''If you revert to factory 
setftngB, you will lose any cool settings of your own that 
you have niade. (10,3 version)”!: 

// chiHXic ^Icrt kind 

ItheAlert setAlertStylerNSWarnlfigAlertStylel : 

// roll oui ihc sheet! 

//We re not using a tldcgiitc or Us hook, if wc wcr‘, 

// wc w<iuUI ilcfinc 41 iiiLthod c;tllc(J 

// aJcrtDklEfMlnrtunKxidcx'onicxtlnfti and 

// pass oij»siiLTtoitakTmkJIUiit:relitrnC(Hk:ccmtcxtlnf<>:> 

// rbr dkitndSclccior and self f<jr modatlX'lepaic 

ItheAlert beglnSheetMndaTFortfindow:[sender window] 
aiodalDelegatfl:nl 1 
didEnd Se1ect o r:nil 
ronrcxtlnTo: nil]: 

I 

This completes the basic fnimework our sample app. 
Note that ix^cause wcV<? created a dcK-ument-based applicalitm, 
we can open as many window.s as we want, and each one 
comes with sheet-displaying abilities. For Fun, open a whole 
mess of them and drag them around. Wheel 

As with all software, there are a jillion ways we could 
enliance our little app (such as by making it do stime actual 
work instead of jiisi demonstrating how to put up a lens). For 
example, we could take the Knglish text out of the code and put 
it in a property hst, which would lie beUer for localization. We 
might try a ciLsiomized sheet, which we can make with the 
beginSheet:modalForWindow:modalDelegate:didEndSelector:context 
Info: method of NS Application. Delve into the deHnitions and 
dtRumentation for NSAIert. NSApplication, and NSBuUon fcRmore 
exploration. Extending this example is a great way to get started 
playing around witli Cocoa. You can downlcxid the XccRle 
proiect fixjin hti p://www.pa percar.com/iiH/KedAlcn ,zip. 

Until next month, have fun, .stay alert, and please yell 
(scottk@mactechxom) if you are [laying atlention. 
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CASTING 
YOUR .NET 


Andreu> Troetseri, Minneapolis, Minnesota 

A Primer on the C# Programming 
Language (Part One) 


Exploring ,NET development on Mac OS X 

Topic Prelude 

If you have read the previous insiallmcnis of this series 
(except last month when I missed the deadline), yt)ii should 
be well aware that the .NET platform is langiia^?e agnostic. 
While this is technically correct, \\\ be lying if! did not admit 
dial C# is currently the language of choice for a majority of 
.NET developers. Given this fact, my goal in the next two 
issues is io offer a lour of the major syntactical features 
provided by llndersiand of course, that two articles 
cannot possibly examine eacli and every token and const riici 
of a given language. In any case, once yon have digested the 
material presented here, you should feel cjuite comfy with 
tlie core aspects of anti he in a perfect position to follow 
along with the a nicies lo come. 

ReCAU. the PlllARS oi OOP 

All object languages musi contend with the diree ‘pillars 
of object odenicd programming' (OQE). Eirst, an OOL (object 
tiriented language) must address the concept of 
encapsuUiiioft. Simply pul, encapsulatum services prtwide a 
way for lyfies to safely control access lo their private data 
points. Next we have iftberUance, which provides a manner 
in which exiting types may be reused and extended. List l>ut 
not least we have the third pillar of OOP termed 
fK)iymofphism. ‘I'his pillar of OOP allows related types to 
respond uniquely to the same method invocation. Given that 
C# is a modern OOL, you are correct to assume that 
prtivides cimiplete suppiiri for the j>illars of OOP, as well as a 
relatively new paradigiti termed aspect otiented profirammin^ 
(AOP) whicli will be examined in a later article. Belbre we dig 
into the details of OOP using C#, let’s check out ba.sics of 
defining classes and allocating objects. 


Dehning Ciass Typi-s in C# 

Classes are the crornerstones of any OOI, in that they 
provide a template for the objects that comprise your 
application. In C#, class types are defined using (not 
siinmstngly) the ‘class' keywxrrd. Like other languages in the C 
family, classes may support any numl>er o( overloaded 
construclors to allow an object to ctinie to life in a particular 
state. To illustrate, assume we have a class named Car 
(defined in a file named car.es), which defines three pieces of 
private data lo represent a given auumiubile's pet name, 
current speed and make (lasting 1). 

lining I A simpk O cbLvs definition (car.cs). 

using Systems 

naiof'Rfrace CSharpPOPliKtiti|}le 
I 

//lilt’ (M cbs*i 
public, class Car 
1 

// Suilc U'uLilit tx' defined as paitccicU if desired), 

private string petMnme; 
private Int currSpecd: 
private string iiialne: 

// CcmsinKiiir so. 
public Gar Oil 

public Ccirfntring pn, int cs. string tn) 

I 

petNane ™ pn: currSpeed *= cs: 
make = 

I 

// tKcrridc tlic virtitijl inctlKKl Sy-stm-Ofiio r TuStringO 
// in iirdcr uj display intr stale daU. 
public override string ToStriiigO 
{ 

return strIng,Format( 

(Oh Speed; til; Kake; t2J*. pciHame, 

CUtrSpeed, tiakc) ; 

I 

I 

1 


Andrew TrocJscn Ls a seasoned .NET develo(x?r wlio ha.s authored numerous Lxxjks on tlie topic, including tlie award w inning C'^ and ibe ,NFT 
Platform. He is employed as a fiill-tijne .NET tminer and tonsultant for Intertech t mining (www.inlertechtratning.com), hut thinks lie is still on the benches 
of Mexico sipping funky drinks served in coconut .shells. You oni coniaci Andanv ai atroelsen@mac.com. 
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Multiple formats. Multiple platforms. 
Complex installers. 

Aladdin solves the compression and installation puzzle. 


Trying to figure out how to handle multiple 
compression formats and platforms? 

The Stu fflt Engine solves the compression puzzle. 

Aladdin’s SUiffIt lingine SDK: 

> Adds value to your application by integrating powcrftil compreSvSion and encryption. 

> Is the only tool that supports the Stufflt file foniial. 

> I’rovides a single API that supports over 20 compression and 
encoding fonnats common on Macintosh, Windows, and Unix. 

> Makes self-extracting archives for either Macintosh or Windows, 

>■ Available for Macintosh, Windows, hinux, or Solaris. 

Stufflt Engine SDK" 

The power of Stufflt in your software. 


Licenses start as low 
iLs $99/y«ir 

To Icam more, visii: 
ww'w. stuffit. coiTi/s( ik/ 




Looking for the easiest and fastest 
way to build an installer? 

SlujJIt InstalkrMaker completes your puzzle. 


It’s not enough just to write solid code anymore. You still have to write an installer 

for your users. Stufflt InstallerMaker makes it simple and effective. 

> Stufflt InstallerMaker gives you all the tools you need to install, uninstall, 
resource-compri'ss or update your software in one complete, 
easy-to-use |)ackage. 

>• Add marketing muscle to your installers by customizing 
your electronic registration fonn to include surveys 
and special offers. 

>• Make demoware in minutes. Create Macintosh 
OS X and Macintosh Classic compatible installers 
with Stuffll InstallerMaker. 

Stufflt InstallerMaker 

The complete installation solution'*' 


Prims Shirt ai $250 

To leam mare, visit: 
www.sluffit.com/ 
insUdlcniiaker/ 


^ ^Aladdin 
m^Systems^ 

www.studit.com 

(831) 761-6200 

© 2002 Alotddm Syifwmj. 

Inc. Stufflf, Siufflt 
tnstalletMokef. ond Su/ffh 
Engine SOK are lradiinark& 
of Aladdiio Systemj, Inc The 
Aloddin bga 14 a regliterad 
hqdemqrk. All odw pfoduefs 
are irodemaTb or rnglslered 
trodemarki of Hisir reJiperNve 
holders. All Rights Reservod 













Thu first point of imurust has to do with the 'public' 
keyword used when defining lliu type. In C#, a non-nested type 
may he defined as public or Internal' (the defaiili). The 
distinction is made clear wlien you recall that types are 
contained within an assembly. Public types may l>e createrl and 
manipiihucd acrt>,ss assembly boundaries. On ihe other hand, 
internal ty[>es can only be createrl and usc‘d l>y the assembly that 
defines it. ITius, if ycni were to build a .NiH' assembly which 
contained three public types and two imernal lypes, other 
assemblies would l>e compleiely unaware of tlie two internal 
types. Using this lechnkjtie, assembly builders are free to define 
any numl)er of internal helper types that are invisible to other 
binary units. 

Next, you can sec that we have defined a method 
named ToSiringO using the C# 'override' keyword. This 
brings up a very important point regarding the .NET 
platform: If you tlo not say otherwise, class types 
atifomaitcally derived form the cosmic base class, 
System.Object (intrtjduced in the Ocioher 2003 installment of 
Casting your .NE’H. Like many Irase classes, Ob|ect defines a 
set of virtual meiliods that may be redefined (w'hich is kj say, 
(werridticn) by derived classes. Here, the virtual 
System.Object.ToStringO method has been twerrklden in 
order to return a custom l)lurb of text which represents the 
('urreni state of a given Car type (the defauli implumentation 
of ToStringl) returns the type's fully tpialified name). We ll 
examine the details o\' virtual members and member 
overriding a bit later in this article. 

Finally, noie that the Car class has two comstructors. The 
role of our custom consirucior is clear enough, in that it 
allow.s the object user to create a car in an initial state. The 
other constructor may seem a hit f>dd (depending on your 
exposure to other C based languages) in that it’s 
implementation does nothing a! alL like Java and 0++ 
always supply a freebee no-argument constructor (termed 
the default constructor) for each and every class definition. 
However, as .stum a.s you define a custom constructor, the 
default, defauli constructor (pardon the redundancy) is 
removed. Ilierefore, if you with to allow objects of this type 
to be created with no arguments, you must redefine the no- 
a rg u 11 1 e n 1 ct > n si ru c U j r. 

On a final constructor-related note, recall the Ci*' 
aiilomatically .sets a ly[>e's state data to safe default values (cjuiLc 
uniike C++). Tlte rules are quite simple: 

• Numerk al data is set to 0 or 0.0. 

• Objed references are set to null. 

• lit K)1 ea ns a re .set t o fa I se, 

Given this language feature, we have no need to as.sign 
values to petName, currSpeed or make within the scope of the 
default constnictor 


Allocating and (hidirectly) Destroying Objects 

We are now' ready to create an application object (e g,, the 
class defining the MainO rrietliod) to allocate an auto or iw(> 
onto the managed heap (listing 2). 

[JMirtj* tcarApp cs> 

ufiing 

riiinespace GSliarpOOPSxajJipie 
I 

//'the App 

internal class CarAppUcatlon 
[ 

// Prx^jsnmi's eniry point 
private static void HeinO 
I 

// Make Mjme Cars! 

Car noHame “ nev C^rO: 
CoQfiole.WritfiLlnfitnnKame.TDStringU J; 

Car soEteCar = new CQr{**Zippy",. 90, 

//ToStriiigO uallfd initomiitically 
Console.WriteLine(someCar): 

1 

I 

I 


In C#, the 'new' keyw<>rd is used to allocate an insiance 
of a given class type unto a region of memtjry termed the 
managed heap (in fact, clas.s lyi>es can only be heap 
allocated. Stack allocated data is achieved through the use of 
value types, as descniied in the next issue), hi a similar 
fashion as the Java platform, .NET provides a garbage 
collector that is in chai-ge of destroying unused objects wlien 
rerpitred. Given this, C+ does not provide a <'orresponding 
keyword (such as 'delete*) to explicitly destroy an object. 
I iowever, does provide a syntax which looks suspiciously 
close to a C++ style destructor. Ponder the following updated 
Cair type (Listing 5): 

Listing 5.C^ slyk \trstriicti>rs’. 

//The updaiol Car t:bss lypc 
public class Car 
t 

"CarO 

! 

Console.Wrlcel.ine(*'Thia car is destroyed,"’]: 

[ 

1 


Like C++, destructors are syntactically denoted using 
a tilde prefix, Inmever the similarities end here. First and 
foremost, a destructor i.s in reality a short liand notation 
for overriding the virtual Sy,Htem.Ohject.Finaltze() method (to 
verify thi.s for yourself, run your a.ssembly througli ildasm 
anti check out lu>w C# destructors are expressed in terms of 
CIL code). Next, remember that C++ memory managemeni 
i.s quite deterministic in nature, in that we programmers are 
the individual.s responsible for destroying heap allocated 
memory. In contrast, the .NET platform uses a non- 
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dettfrniinistic rinalizaiion approach. In other words, you do 
not know exactly when the garbage collector will remove an 
object from the heap, only that the associated memory will 
eventually be reclaimed. When the object is indeed 
destroyed, the .NIH' runtime will ensure that your type's 
destructor is invoked if present. 

As you itiiglu gue.ss, iliere is much more that could fie said 
about the .NET garbage collection process (such as 
programmatically controlling garbiige collection using 
System. GC, iiupleinenting the 1 Disposable i ate dace, object 
generations, etc), liowever ifie current explanation will suffice 
for now', 

ENCAPSifiATioN Support via Twe Properties 

Our current iteration of the Car type is dysfunctional to 
say the least, as we have not provided a way to get or set the 
state data after the lime of ( onsiruction! .NE1' programming 
languages prefer the use of type properties, rather than 
traditional getters and setters to honor the jiiliar id' 
encapsulation. In tlie Fefiniary 2004 issue you examined 
property syntax via JScript.NET, and wall be happy to know 
tiuu the act of defining properties in is quite similar. 
Listing 4 illustrates how to pre.serve encxipsulution of the 
private pel Name member variable using a public property 
named Name (assume that the make and currSficed member 
variahles are encapsulated i)y additional properties; Make 
and fipeed respectively ). 

Liitinji 4. C* pnjperty ?frr«ax. 

public class Car 
i 

private string petNaite: 

// Ct P(x}pcrty syntax, 
public string Name 
f 

get ( return polNuflitu I 

set I pel Name ” value: t 
I 

I 

Recall that the name of u property does not need to have 
any relationship to the name of tlie data point it is resp<jasih!e 
for exposing. Also note the use of the ^'alue’ token in the 
implementation t>f the property .set .scope, 'rnith be told, Value' 
Is not really a true-blue keyword in the programming 
language given that it is legal to define inemlKT variables or 
loail variables named Value', However w'hen this token 
appears in the context of a iiro[H-*ny .setter, it is used to repre.sent 
die incoming value assigiimenL Finally, it is worth noting that 
propertie.s can lie cxinfigureil as read-only or write-only. Simply 
omit the get or set scope from the property definition. 

For testing purposes, update your Main() metliod lo change 
and obtain various data points (listing 5). 

listing 5. Exi'Tdsmg oiir pitifx’riies. 

internal class CarApplication 
I 


// Pnigraoi’s point 
private static void HainO 

I 

Car someCar = naw Car C"^i ppy". 90, 
so me Car .Name ” ’‘Junior": 

Console. WriteLine(" I 0] ts going (li HPtf.”, 
soroeCar.Namc, someCat.Speed); 

I 

I 

At this point you can compile yourC^ files into an executable 
assembly (don't forget to enable an SSCLl-awarc Terminal). The 
commancLs li.sied in Kistmg 6 wilt do the job nicely, 

listing 6, (iimpilinig and executing uur Car appliotlon. 

DoSseli 

CSC '.cs 

cll* csrApp.exe 


Nexi Up, we whll examine how to iKiild a set of related 
types using classic inheriUince. 

The Syintax oe Inheritance 

As mentioned, if you i)uild a class type that does not 
explicitly spet^ify a Ixise class, youriype will automatically derive 
from fiysicm.Object. However, wdien you wish to build cla.s.s 
hiemrehies you will no doubi Ixr interested in deriving new' 
types from existing class definitions. Tills is accomplished in C# 
using tile colon operator. Let’s cjcate three child classes 
(SjKulsC^r, MiniVan and [amesBondCarJ that leverage our 
current Car type (assume eacli of these new iype.s are within a 
file named childCars.es and are wrapped wiJhin the 
CShun>OOFExainple name.space), lisling 7 defines the 
SporisCar tyi^e. 

listing 7.Tlie Sportstiir class ty-pc (chikir.ars,cs). 

// .SpnrtsCiir IS-A Cat. 

public class SportsCar ; Car 

I 

public SportsCar(string pn, ini cs. siring in) 

: baaefpn. ca. m) 1) 
public SportfiCarOn 

public void TurbaBoustO 
E Spend 2 €: J 

1 

HeyoncI the fact that SpcjrtsCar is expliciily deriving 
from the Car type (and therefore inherits each of the public 
and protected members of it's base class), observe the use 
of the ‘base' keyword in the custom constructor. As you can 
see, 'base' is dangling off the constnictor dennUkm by way 
of a single colon (which in this case is noi marking the name 
of the ba.se class). When the base key weird is used in this 
mamicr, you are spec:ifying which constructor to call on die 
parent class when tlie derived type is created. Given that 
Car already has storage for tlie pelName, currSpeed and 
make data points, we are explicidy calling die three- 
argument construclor of the parent. If we did not do so, the 
parent's default constructor would be called automatically, 
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forcing us to set the private data points using the inherited 
pul)lic: properties or possibly protected data (which is 
obviously less efficient). 

As well, notice dte iiiipletnentation of the 'I'lirlioBocxstO 
met both Another lx>nus of property sy^nrax is iliai iliey respond 
to t!ie intrinsic operators of C#. Thus, nillier than having to 
incre;tse die SpoitsCar's speed using traditional accessor and 
mutator k^gic ( Listing 8) we can use the more streamlined ccxie 
“Sfieed += 2a;\ 

listing 8. pRJi^rtks sta'amlinc tr^^jiiiunnl get / set logic. 
// If wc were not using ptx>pcitics... 
public void TarboBDOiJtO 

I 

sntSpecdCgetSpeedO + 20): 

J 


Listing 9 details the MiniVan type, who's first point of 
inieit*st is that the custom constructor passes three of the four 
incoming arguments to the base class, while assigning the fourth 
and final parameter to it's own custom point of data 
(numlierOlXids), ALm) notia^ liow Mini^lan overrides the parenfs 
impiemeniatiori of TaSiringO to acanmi for it's taisiom piece of 
stale data. In this case, the *base' keywirrd is not triggering a 
base class construcior using the ^dangling colon on ihe 
constmiior’ syntax, but simply oilling a Ixtse class metliod 
within tlie scope of the methfxl definition. 

listing SI Tlic MiniVjm cte type (diddCaFS-cs). 

// MiniVan IS-A Qir. 

public class KiniVan : Cnc 

t 

public HtniVan{strlng pn. int ce, 
siring a, int k) 

: batvctpn. cs, m) 

I 

nuTObecOfKids = k: 

I 

public MlniVanOll 

private itit numbec0fKids: 
public int KidCount 
t 

gat f rc^t urn nuabaiOfKidc: I 
set ( numberOfKidf! = value:! 
t 

public override at ring ToStrlng{] 
f 

return string.Format£“101: kida: tl!". 
baso.ToStringO. numberOfKids): 

1 

I 


Finally, Listing 10 illuslniles the final automobile, 
JamesBondCin Note that JainesBondCar exteniLs SfioitsCar, 
which in turn extends Car (which extends System.Object), 

I.istirtK ja nx' jumcslHmdUir djiss lypu (childCars.cs). 

// tanicsUondCmr JS A SportsCar 
// wliidi IShA Car. 

public class JamesBondCar : SportsCar 
I 

public JamasBondCar(string pn, int cs, string ra) 


: basefpn, cs, m) tl 
public JamesBondCarO I ] 

public void DlvellnderWater() 

[ Console.WritBlina{**Diving under water! “):] 
public void FlyO 

( Console,WriteLlne£**Takitig off into the alr[“):l 

1 

Needless to say, our jamesIiondCar is able to dive under 
water and fly into the air Uj e.scape the airrent enemy at hand. 
Further, given that this type does not add any new member 
variables to tile mix, the parent s ToSiringO implementation w'ill 
fit the bill nicely. 

Building a Array of Car ty pes 

At this point the MainO method may be updated to 
exercise each of these new derived classes. To provide a 
more interesting example however, let's create an array of 
Car types. As you are most likely aware, most OOIjs 
(including Java and C++) allow you to store a derived object 
in a base class reference (e.g,, and implicit cast); This is 
legal given the 1S-A' relationship enforced by classical 
inheritance. Given this faa, update MainO to create an array 
of Car-compatible types and iterate over the array using the 
C# ToreaclC keyword to invoke each ol>iecfs 'IbStringO 
implementation (Listing 11). 

Usiini? 11. Crcsiting «n army of f ^r^compatibk t>'pcs. 

// lifray of ly pts. 

CarlJ allTlieCarii - new Garfl] 

( new SportsCiir£”Zippy“. 8^. "Audi IT'’), 
new HiniVant-KidHobile", 55, “Caravan". 10), 
new JaiiesBundC3r("QMobile“, 120, "^Classified*'*)): 

// Prifit mil the number uf curs in unuy. 

Causolo-tfrlteLine("Ynu have tOI cars:", 
ailllieCarG .Length): 

// ( 4111 cuc'h uulu's'ltxStringf.) lui thfjd. 
fo reach (Gar c in al lTlieCars) 

Console,WriteLina(e.ToS t riug C)): 

A few points of inieresL tn C*, arrays are declared using 
the (Mike .stjuare [^racket notation. Here we have created an 
array of Car types named ain'heCar.s. The ‘new* keyword 
used when declaring ilie array is noi creating any particular 
Car type, but ratlier the underlying System.Array in the 
bac kground. Given that C^ arrays always derive from the 
System.Array ba.se ckiss, each array has access to each of the 
pubhe mem tiers (such as the Length property seen in the 
previous code segment), 

Once we have allocated a System,Array capable of 
holding (3ar-compatib)e lype.s, w^e can leverage the curly- 
hrackei sljorthand notation to fill the array W'ith sub-elements 
at the time of creation. If you would rather, you are free to 
allocate and initialize an array on an iiein-by-iiem basis 
(lasting 12) 

List Lug 12. CR'PTiag :uTay of r,ar-com|>:uihk lypety (llic long w^) 
// Ijong lund amy ctr4tiim. 
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Car[J allTheCars = aev Car[ 3 h 

allTheCaralO] * new SportaCarC‘'Zippy*. 8^^* "Audi 'rr">: 
aimeCarsII] - 

new MlnlVanC-KidHobile*. 55, “Caravan*, 10); 
allTheCars[2] - 

new JaiRcaBondCarC'*QMnbllc", 120. “•Classified"”): 


The Details of C#*5 Toreach’ Keyword 

Speaking of System.Array, if you were to look up the 
formal dcriiiitiun of SysStem.Array using any of the loois that 
ship with the SSCLl (see Feb 2004) you will find ihai ihis 
class type im piemen is an interface named 
S y s i e m . C o 1! e c t i o n s , I E n ii ni e r a )■» I e . 
System.Collections.!Enumerable defines a single method 
named GetHnumeraiorO, wiiieh returns yet another interlace 
named Sy stem. Col lections JEnumera ton This interlace 
provides a way for a type to iterate over contained sulvitems 
using three members: 

• Current; This property returns the Item current *fKitntetl to\ 

• ReserO : This method resets the internal indexer's position to 
the first item. 

• MovcNextO : As you would guess, this advances in the 
internal indexer by one. Keiurns false when ihe end of the 
list lias been readied, 

why do we care about 1 Enumerable and 
I Enumerator? Well, ihe Torcach' keyword of C# is 
preprogrammed to oi>tuin these underlying interfaces to 
traverse the sub-objects of the array being iterated over. 
Given that all of these sub-objects have a ToStringO 
implemenuition, we can safely invoke each auto's custom 
version. Be aware that System.Array ts not the only type 
which implements the necessary interfaces recjuired by the 
foreach construct. Most of the class types found within 
>Sy stem,Col lection support similar infrastructure, and if you 
wish to build a strongly typed custom collection, you can 
implement tliese interfaces tlirectly to traverse custom types 
using Toreach'. 

ThI' ABCs of Polymorfjiism: ViKit?Ai. and Absihact Mijhbers 

The final pillar of OOP to examine is poly morph Lsm, 
which you have already begun to levemge when yt>u twerrode 
the virlual Sy stein.Oliject.ToStringO and 

System,Object.FinalizeO methods in your custom class types. 
As mentioned, da.ssical polymorphism is the trait cjf OOE that 
allows hierarchies of types to responding uniquely to the same 
message (a.k.a., method invocation). Polymorphism is 
supported in G# using four simple keyw^ords: 

Base: As already seen, 'base' allows you to trigger a parent's 
method / amstructor 

Virtual: 'lliis keyword allows you to define a hast' cla.ss 
method ilial iias a default implemeniaiion, Imt may be 
overridden by a child-dass if required. 


Abstract: This keyword allows you to define an abstract 
base class (ABC) as well as abstract metlitKLs. Recall that abstract 
classes cannot be directly created, l>ui can l>c used to hold 
references to derived ly[K’s. Also recall that abstract methods do 
not have a default implementation, and therefore derived types 
must provide a concrete implement at it m, or define tlieinselves 
as abstract classes as well. 

Override: This keyword ullow.s a derivetl class to redefine a 
virtual method a.s well as implement an abstract member. 

To inject some [)olyinori>hic activity into our existing 
application, Jet’s add an abstract method to our Car base cla.ss 
called PrintBumperSiickerO. Re aware lhal when a class defines 
an abstract memlx:r, the class must also be marked as abstract 
(listiug 13)- 

tjsiing 15. The abstract Car type. 

//llic ahsir;ici Ctrda^ type 
public abstract class Car 
I 

// All derivetl da-s-ses mu-st 
// implement thus member (ir become 
// ah^ract Jis well. 

public abstract void PtiiuKyittperSt Icker (); 

T 

Given that Car has now been redefined as an ABC, it is a 
compile time error to tliredly create Car types. However Car 
(and ABCs in general) still has a very useful jmrpose, in that i! 
defines all of the common funetionalily for derived types. Car 
has Ix^en fiinher updated with a single ahsimct member, and 
therefore each and evei 7 derived class in now required to 
provide an implementation of this iiieiiifx'r (if you do not, you 
are issued compile tune errors). 

To rectify this issue, update SportsCar, MiniVan and 
JatiiesBondCar as you see fit using ihe 'override' keywcxtl 
Listing 14 shows one pt^ssible implementation for the 
MiniVan type. 

Usiing 14. MiniVkn s lYirullumpcrSiickcit) impttTTiufimifiin. 
public class MiniVan : Car 

I 

public overridp vciid PrlntBuiiiperStlckerO 
1 

Cotisole. WrituLiue 

(“All my raciney and Kida go to the U oL Mn.”): 

1 

T 


Rtiittime Type Discovery using C# 

Now that we have a polymoq>hic inierfaee defined by our 
base class, we c:m update ottr MuinO melhcxl to in\a>ke each 
type's cu.siom implementation (Listing 15). 

Usiifig 15. Pol>'uw>q>hism at work. 

f oreach (Car c in aUTheCacs) 

[ 

Console.WriteLine(c.ToStrlng()); 
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t.PrintBumperStlckerCJ; 
Consols .i 


listing IH. Maniiall)^ handling an InvaliffCastExecptioii. 


1 

UntlcTslancJ that the code within the roreadi block b 
only legal because of the defined polymorphic interface. We 
can rest assured that all types have an implementation of 
ToSlringO given the fact that all classes ultimately derive 
from Syslem.Object, and that all descendents of car must 
implement the abstract PrintBumperSticker() method. 
However^ what if we wish to call specific members of the 
jamesBondCar, MiniVan or SportsCar types? If you look 
closely at the foreach syntax, you can see that we are using 
a base class reference to represent each sub-object. 
Therefore, the following would be a compile time error 
(iJsting l6), 

tisting tfi. dta'Vtl)^ access dL-iIvtd tjTXr mcmlscrs frura a huiM: class refcrcm^ct 

toreachtCar c in allTheCars) 
i 

// NypcI Cju- tk>cs ncji dcliuc a (CidCxiiiat 
// projicrty! Compilcf effr>rt 
Int mimhf'rOfKids - c.KidCaunt: 

] 

When you need to dynamically discover if a given type is 
companihle with a given base class (or interface), C# [provides 
two keywords. Ponder the following update (Listing 17). 

listing 17. Runtimt? type dlstoviny In CM 

foreach(Car c in allTheCara) 

[ 

ConnDle.Writcl.tnctc.ToSLrlngO) i 
c.PrintBuittperSLickerO ; 

ff B 'c' a JamesBondt^ar? 
i£tc is JaaesflondCar) 

((JaiaesfiondCir) c) .DlveUnderWatet (); 

// h ‘c‘ a MiniVafi? 

HiniVan m - c as MiniVani 
lf(ni !“ mjM) 

Coni;ole,WrlleLinet"i have fOl screaming kidsl". 
tn.KidCuuuL) ; 

Console.WriteLinaO ; 

I 

The 'is' keyword Ls quite helpful in that it returns a 
Sy,stem.Boolean that denotes if the current object is 
compatible with a given ba,se cla,s.s (or interface type), if the 
rest succeeds, you can make a safe explicit cast (using the 
familiar C-.style ca,sttng syntax) to access the underlying 
functionality. The 'as* keyword is similar, however *as' will 
return a null object reference if the types being tested are 
incomf)iiLible. Therefore, when performing a runtime check 
for type compatible using the *as' keyword, be sure to test for 
null before casting! 

On a final casting related note, you can make use of one 
additional construct to check for type compatibility; stmciored 
exception handing (Listing 18). 


// Is 'c' Sp<>rts<4ir coinpatihfc? 
tryl 

f(SportsCar)c).TyrboBopst{) ; 

J 

catch{IttvalldCastExcsptioTi ex) 

I 

Cgnsoie,HriteLine(“OOPS! Not a SportsCar.”)j 

Console.WriteLioe(ex.Message): 

I 

Here, we are making u,se of stmt tured exception handling 
to attempt to cast current item pulled from the array uf Car- 
compatible types into a SportsCar. If the cast fails, the runtime 
will throw a Sysiem.lnvalidCa,stRxcepfion type. Given that all 
exceptions derive from a common base class named 
System.Exception, we are free to make use of any of the 
inherited mcmlx^rs to display information about the error in 
question (such as the Message projKHy). See online help for 
ctrmplete details of System.Exception. 

iNimACL-BASi^ Polymorphism 

Excellent! At thi.s point you have a solid understanding of 
him C# oimends with the mighty pillars of OOP and gained 
.some insights into runtime iyf>e discovery, cxplidi casting and 
structured exception handling along the way. To complete iliis 
article, we will shift away from our examination of class types 
and examine the role of intcHace types (remember that .NEl' 
defines five possible types from the set (class, interface, 
sirucLtirc, enumeration, delegatel). 

Interface types, in a nutshell, are a named collection of 
abstract (and only abstract) members. On its own, an 
interface is of little use, given that you cannot create an 
instance of an interface varialile. However, when an interface 
is implemented on a given class (or structure) you are able 
to liind a set of behaviors to the type in question. The power 
of interface-based programming becomes ciy^stal clear when 
you understand that these types allow you to breath 
polymorphism into types found in different class hierarchies. 
Let's see a complete example. 

Assume you have created some new class type modeling 
tIFOs. Given that LIFOs (presumalily) are not autoinobiles, the 
UFO base type will derive directly from System.Object, whereas 
Mothership extends UFO (listing 19). 

lining l9.Tlic UK) elm types (ukjs.es). 

Ttunoiipfteo CSharpOOFExample 

I 

public class UFO 

I 

public void AbductKiimanO 

I Console.WriT.eLine(“Come hero Earthl Ing..J; 

I 

public class MotberShlp UFO 

I 

public void AbdtictOtherUFOsCJ 

I Console.WriteLine 

("You have violated the prime directive."); ) 
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At this point, wti have two distmet hierarchies (car-types 
and IJFO-iypcs), When you look at the classes defined in each 
category, it might strike you that UFO, MocherShip and 
JaniesBondCar could shun; common l^eliavior m that they all 
have the ability lt> iK'Come airborne. If you wish to build a 
further a.s.sociation between these types, you won’t get very far 
with classical polymorphism given that virtual and abstract 
methods in an ABC are only useful if the types are in the same 
hierarchy (wdiich is not the case here). However, if you pull the 
common functionality into an interface definition, you can 
selectively attach this iK^liavior on a type-by-type basis. To 
illusirate, define an interface named tAirVehicic w'ithin a file 
named interfacesrs i listing 20). 

UsiiriB 20. Tilt? lAkVehldc bacrfacc (iutcf&ccs.cs) 

mme space USkarp 00 PE x amp 1 e 

I 

public interface lAirVehicle 
i 

void Hover{): 

bool CaoLeavoAtnosphere I get ;} 

I 

) 

Here, lAirVehicle defines a single metfiod and a read only 
property. Again given thai tnierfaccs are nothing but a named 
collection of al)SLracT tneihods, we have no impleineniation 
deiails, no access jnodilier (interface methods are always pul>hc) 
and no member variables. 

Once an interfac'e is defined, it may now i^e implemented 
by each type that should support this behavior First, the UFOs 
(Listing 21). 

listing Zl.fmpkmentiiiy lAirVchidc on ihc UFO types, 
n^ntefipace CSharpOOPExaraplc 

f 

public class UFO : lAirVt*hicle 

I 

// Wiirk lAirVehicks.HovcrO as virtual 
// to allow tienved types to modify this 
// Ix'luvior. 

public virtual void Hover() 

[ Console.WriteLine 

(‘‘Hovering and observing humans..."’); 1 

public bool CanioaveAtmosphere (get (return true.;! I 

I 

// Bt't'mtse MorhefShtp tkrives fnrni UFO. 

// ii is automatically (AirVchicIc 
tl 

public class HotherShip : UFO 
I 

public override void Hover() 

[ Console.WriteLine 

('‘Hovering and observing other UFOs.,.’’); 1 

1 

t 

Implementing an interface is an all or nothing 
proposition. Given that UFO states that it supports 


lAirVehicIe, it is now t>bligated to implement Flo vert) and 
Can leave Atmosphere. Notice that when UFO does 
impicmeni the IloverC) method, it marks this memlx^r as 
virtml Thus, the derived MoilicrShip is free to redefine how 
it will implement thi.s functionality while still being type 
compatible with lAirVehicle. Now, let’s implement this same 
interface on James Bond Car (Listing 22), 

Lbling 22. IniplrmeiHing lAirVehicle nn lamcsHondCur. 

public cla;5s JamesRondCnr : SportaCar, lAirVehiclea 
( 

public void Hover{) 

I Console.WriteLine 

("Observing ColdFinger and OddJob...**): J 
public bool CanLesveAtmosphere (get (return False:) I 


Note that when you wisti to explicitly mark a type's base 
class as well as inipiement some set of interfaces, ytju simply 
make use of a comma-delimited list (the first item after the semi¬ 
colon used on the class definition will always mark the base 
class). Given ihat UFO derives directly from System .Object, we 
can simply list the set of supported interfattfs wiiliout explicitly 
deriving from Object (as this is assumed). 

Interfaces in Action 

At this poim, we have tliree difterem classes (in distinct 
hierarchies), which implemcni the same interface. Now (hen, 
whai IS tlic iKmefii of doing so? First of all, you can declare an 
array trf types that implement a given interface to exercise 
interface-based ptrlymorphrsm ( listing 23). 

listing 25. Intcrfocx- types as annjys. 

// i;rcaif aji amry of lALrVtdiicli* I'ompaiihk lypr^s. 

lAirVehicle [J myFlyingObjects = new TAlrVehicle[4|: 

rayFlyingObjects (Oj « 

new JnmeaBondCar (“ Birame r’*, 120, “ * Cl a se i f 1 ed * ”); 
inyFlyingObjects [1] - new tJFOO ; 
ttiyFlying0bJectsf2] ^ new UF0{) : 

TByFlyingObjectsfi] “ new MotberSbipO: 

foreachClAirVehiclo aVCompatibleType in myFlyingObjects) 
t 

Conaole.WriteLlnet"Can leave atMOfiphere? {01"^ 
aVCompatibleType.CanLcuveAtraosphere); 

] 

To deepen your aftfirecialion of interface programming 
lechni(]ues, assume we now which lo create a 
System.Collections.ArrayUst type within t>ur MainO method. 
Because the AdcK) method of I lie Array List type is proioiyped to 
take System.Objects, you can add literally anyiiiing initi the 
container (Listiiig 24). 

Luiiing 2A, P<kfubtmg iiurAmylist whJi numerous things.. 

ArrayList allMyStuif “ new ArrayLlstO; 
allKyStuff .Addtnew JainesBondCar 0): 
anHyStuff.Add{22); 
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allKyStuff.Add{"Ge Baldy» it's your birthday,,."}! 
allHyStuff.AddCnew HlniVatiO); 
allHyStuff,Add(Ti(»w Kothc^rSbipO h 
allHyStuff.AddC false?); 

forcacti(ob|ecL o in allMyStuff) 

( 

Ifto is lAirVehicie} 

C(IAirVehlcleJo],Kover(Ji 

else 

Consal^!.y^^toLlnoCaorry, not an air vehicle.’*] : 

i 

Here, the object contains nLinicrous iinrclatecl 

items (James BondCars, System. Int32s, System. St ring tyj)es. 
System.Boolcans and so on), however we are able to 
investigate each sub-item using die 1s' (or Its') keyword to 
dynamically di-scover which items are lAirVeiiicle 
compatabic. If ihc nirrent item is lAirVehicle aware, we cast 
the object accordingly and call the HoverO method. Again, 
the beauty of the interface is the fact tliat we can inject 
polymorphism across diverse class hierarchies. Furthermore, 
given the language agnostic nature of .NET, it is 
common place to define an interface in one prograiiiining 
language and implement it within another. 

Like garbage collection, lit ere are numerous other topics 
regarding interface based prograimning tecliniques under 
the .NET platform (explicit interface implementation, 
interface hierarchies, mu Itipie iniieriLance of interface types 
and whatnot), however well need to cal) it a day for the 
time being. 


Wrap Up 

In this installment of Your yt>u examined 

how the C# programming language contends with the pillars 
of OOP. Once you drilled through the basics of class 
definition and object allocation, you saw how to define type 
propenies in the syntax of C#. Next you created a hierarchy 
of types using classical inheritance, and injected some 
polymorphic behavior using abstract methods and interface 
implementation. In the tiexi article, I'll complete this C# 
primer by examining the remaining .NET types 
(enumeraiions, siructures and delegates). See ya ne.xt issue, 
and happy hacking. 
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By Aaron Mont^^omfry 

Documenting your code 


Generating code documentation with 
doxygen on Mac OS X 

iNTRODDCnON 

One of the nke feuUires of Mae OS X i.s tliat it opens up 
access to u large number of tleveloper tools that used to be 
restricted to UNIX and Windows. One such T(X)I is doxygen, an 
application that aids in axle doc iimcntaiion in a nianner similar 
to javadoc. This article <icscrilx?s how to set up doxygen on Mac 
OS X and assumes that you have only [imired UNIX experience. 
As this article developeil, it Ixx ame moa‘ of an intrtxiuctum to 
UNIX basics inside llie Temriinat and less an imroduction to 
doxygen than I originaliy planned- 'I'his is due l>oth to the fact 
that doxygen already contains a manual and numerous examples 
(that I found useful), as well as the intended audience (Mac 
prograrmners new to UNIX). Tiie anide describes how to install 
doxygen on Mac OS X; how to am doxygen from the Terminal- 
how to run doxygen as pan oi' Project Builder s build command; 
and, finally, itow to extend doxygen to pnivkle diagrams with an 
apfdication called dot. 

'I'he first step to using doxygen is getting a copy of the 
progr4im. There is a [>inaiy executable available at the doxygen 
website listed below (version 1.3.4 ai ihe lime 1 finislied diis 
article). Download the file, dcconipress it and place the resulting 
folder .soiiiewhere. 1 placed mine in the Applications folder. 

WfJXXIMI- IX) Till: SjllilJ. 

Read the following paragraph: 

You wall need to install the doxygen binary^ along your shell’s 
path, You can then re.st your installatkni by dianging to the 
doxygen/examples/ directory, removing the tlirecrory called 
afterdoc, then executing the command doxygen afterdoc.cfg 
(which .should regenerate llie directory). You can browse tlie 
genenitcd doc on lent at ion l>y t)i^ning the hie index.html iaskle 
the afterdoc^tml/ directory. 

Got it? If so, you can prolxilily just skim tlie installation 
section of this article. If tmly some (or even none) of the 
[laragrapli made sense to you, please keep reading while 1 try to 
lead you through the steps carefully in the rest ol this section. 


What I cannot do is give you a full intrtxluction to the UNIX .sliell 
(I am still learning it mysein. If that is your goal, the most 
important UNIX command is man. I used it to confirm that 1 was 
correct wlien I descrilied each command IxHow. You liave 
probably read it before in MacTech, but I will write it again; use 
man frequently xs you explore tlie shell. 

Start up Terminal (in Applications/Utilities) and you are mrw in 
a shell, If you are reading this .section, 1 wall as.sume that you are 
working in ihe icsh slicll witliout much modification (for 
example, the default settings from Apple). Below is a de.scription 
of hoW' to determine if that assumption is accurate. You should 
type in the command following Lhe% syin!>ul and the computer 
shoultl respond with .something similar to the remaining lines. 
Your prompt might be longer than just a single % (probably 
indicating the computer name and your user name), but 1 
removed that inronualion from the examples beiaw^ I will use 
[return 1 to indiaite pre.ssing the reiurn key, antf similarly, [tab] for 
the tab key. 

% echo $VGrsfon[rerurnl 

tesh 6.10.00 (Xstron) 3000 1119 (powerpe apple-darwin) 
options Bb.nla.di ,ai ,siri. rli,color 

Tlic cmnmaiid echo asks the siiell to prim the result to the 
.screen and the expression Sverston asks for the value of the 
variable version. If you arc not running tesh, it might .seem like 
the commands chsh and chpass will allow you to change shells. 
Well, they tlon't (at lea.si not on my macliine). However, die 
appliniiion Nellnfo Manager (located in the Applications/Utilities 
Ibkler) will allow you to change your login .shell. I am going to 
assume that you are using tesh. You can place the doxygen 
executable anywhere, but since you will be executing it from a 
UNIX sliell you will need to make sure the shell can find the 
executable. The shell keep.s a list t>f diix'ctorics that it looks 
dirough when you issue a ctnnmaod- This information us stored 
tn itie variable path You can discover the directories in this lust 
using the command. 

% echo $paLh[return] 

/fiw/bln /Kw/sblTi /bln /abtn /imr/btn /iisr/sbln 
/ usr / locai/teTeX/ bin/power pc appl e d a rwI n -cti r rent 
/usr/local/bin /uer/XllRb/bin 


Aaron teaches mallieinaties at Central Washington University for a living and enjoys mountain hiking in the summer and brewing beer in the wimer. 
You am reach him at monsteFwqtk 5 @nnaccom. 
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If you liavc not installed anything, your path will be much 
shorter. Here is some idea of what these* tlirectories hold (based 
on my poking around inside of them): bin/ direaories hold 
binaries (applications), sbtn/ directories hold system binaries and 
usr/ directories hold user files* When I installed teTeX (a leX 
installation), the /usr/local/ directories were added. When I 
installed fink (an application for managing UNIX packages), the 
/sw/ and /usr/X11R6/ direaories were added. We will discuss how 
to add direaories to your path later in tiie article. For now we 
will use one of the standard direaories that Apple sets up: 
/usr/bin/. If you decide to add dot following die instaictions 1 
tirovide below, you will create the /usr/local/bln/ directory and 
may want to keep dot and doxygen together inside thi.s directory 
(and make appropriate changes l>elow). 

You could either move the application into one of these 
directories using mv or copy it using cp, or do what T am going 
to describe Ixrlow and make a link (the UNIX version of an 
alias)* Personally, 1 place the application in the Applications 
folder so that it is easy to gel to from the Rnder and then create 
a link into the appropriate direaory along the path. 

There are two types of links under UNIX: hard and 
symlxjlic, You will almcxst never use a hard link. Deleting a hard 
link causes the original file to be deleted, a very non-Mac 
behavior (and so not something that sliould lie set up lightly), 
Symlx)lic links behave like aliases, deleting the link leaves the 
original file aione* Tlic system stores a symbolic link as a path 
to the taigel so replacing one folder in the path with an 
idenliailly named folder will change the symbolic link's rargei, 
"llii-s allows you to install upgrades by replacing folders in ifie 
Rnder. In order to facilitate this, I removed ilte version 
infonnation from the doxygen folder's name. 

The following is the command to create a link in the Terminal, 
You will need to l>e logged in as an administrator (for ejuimple, 
using ilie account you cTcaied when you first installed Mac OS X). 
Assuming that you are mimit king my set up, here Ls the command 
(type it on one line, it is split here to fit in the article). 

%1[) -s /Applications/doxygeTi/bln/doxygGn 

/ [returnj 

to: /usr/bin/doxygen: Permission denied 

As a normal user, you are not allowed to touch the /usr/bin/ 
direaory. The trick i.s to find a phone bfK)tli and t:hange into 
your sufKT user outfit. This is not as hard as it seems. The 
command you want to use is the following. 

%sudo In -fi /Appticatlonfi/doxygen/bin/doxygen 
/usr/bin/doxygen[return] 

You should i:>e proinpled for your password and once it is 
accepted, the link will l>e created (assuming you are using an 
administrator account)* Here is a <|uick breakdown on the 
command: sudo tells the .shell that it should exeaite this 
command as an administrator (which is why you will need to 
type in your password). The command In creates a link. The 
option -s creates a symbolic fink* The next two arguments are 


the path to the original file (in Applications) and the path to the 
alias you are creating* You may need to change tills (for 
example, if you placed doxygen in the Developer folder in.stead 
of the Applications folder). If either of these’ jxiths contains 
spaces, you will need to pur the path in quotes or escape the 
space with a Once audienticated, you can use sudo for die 
next 5 minutes witlumt reentering your password. You may also 
warn to make symMic links for doxysearch and doxytag in case 
you decide to use them later* 

You can lest this installation by typing the C(>mniand Ixflow. 

Xwhich doxygen[returnI 
/usr/bln/doxygon 

The which command tells you which file the shell will use when 
you use the command doxygen. On my compiuer, the file 
/usr/bin/doxy^gen will lie used and all is good* But your 
response may have l^een the much le.ss satisfying* 

%whlch doxygenIreturn! 
doxygenL Conimand not found. 

The response here dtx^s not kxik very hopeful The 
problem i,s that the shell only .searches the directories in the path 
variable at starltip and when the path variable Is changed. In this 
case, we have added the doxygen command behind ±e shell's 
back and tieecl to tell it to rechcck the path direaories. Hie 
command rehash does diis. 

%reli.ash [return] 

%which dpxygenfreturn] 

/usr/bin/doxygen 

Next we will use one of the doxygen examples to make sure 
doxygen will run, 'fhe ctjinmand Cd changes directories* We will 
use conimand conijjjaiun to get to tlie example,s directory. Stm 
by typing the fo[It)wing (there is no [return], this is not a misprint, 
do not type [return] yet). 

Xed /AppHiab] 

(_)n my madiine (ancl possibly on yours) there arc multiple 
direcUmes starting /AppI (for example, Applications and 
Applications (Mac OS 9})* Pressing [tab], completes the path to die 
longest sequent:e of common characters and yt>u will need to 
type in st>me more cliaraaers to indicate which one you want. 
This is tesh’s command completion feaRire* If you do not 
rememlier what the next charaaer should be, you c^an type [^D] 
(contmbD) to get a list of all the po,ssihle completions. As 
Ixfore, if you have spaces in your direaory names, you will 
need to precede them witli a \, similarly, parenlhesc^s need to lie 
escapetl Now continue typing (witliout hitting [return] yet). 

/dox[tsb]ex{tab] 

As.siiming your set-up mimics mine, the cxmimand should now read 
%cd /Applications/doxygcn/cxaniples/ 
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and prcs,sin^ [return] will execute the command on the line. 

You can clicck the contents of this directory by typing ilie 
c'ommand 

%ls j moretreturn] 

This Is command asks the shell to list the dirtxiory s contents, 
hw\ rather than just scroll it all onto the screen, wc send the 
output to the more coimriand using a pi|>e (I). The more 
command will wait for you to press [space] l>efc>re scrolling 
down a fiagc ([return] will scToil down one line and q will exit 
the listing). Next you want to remove the afterdex^ directory. Tlie 
rm ertmmand is used to remove (delete) ihings^ 

%rsn afterdoef return] 

rm: afterdocj is a directory 

No gfXHi, plain rm only works for hies. You will need to use die 
-r option to recursively remove the directory {rmdtr -p also works, 
but is more cautious, requiring the directorie.s io be empty). We 
are now geting to use tesh's history feature to edit the incorren 
command. Press die up arrow and the last cointnand you 
executed will return to the command line (repeated up arrows 
will w'ork hack through older commands and down arrows work 
forward), now use tlie riglii/lefr arrow keys to gel to the sjxii jicst 
after rm and add a -r between the rm and afterdoc to get the 
command bekiw (exec^ute it by pressing [return]). 

%rm -t atterdoc 

You can confinn tlmt the directory was removed widi Is 1 more 
(eitiier type it in or use tlic up arrow a few times to return diis 
to the command line and then press [return]). The File .should be 
in the first page of listings. Watch out with Is, it places all capital 
letters before all lower case letters, .so if you are looking for a 
file suiting with ‘"a"', it may actually appear after Files starting 
with Once you confirm that afterdoc/ is missing, you can 
type q to exit the listing. Now we are going to use doxygen for 
die first lime. 

%doxygeTi afterdoc| mote [retyrnj 

You migilt want to stran through the messages or tyfx* q U> get 
back to die command Mne. You t:an check that this worked widi 
die following. 

%cd aft Itabj/h [tab] [rcLum] 

%opeti index.html [return] 

The cd command should move you to the afterdoc/html/ directory 
and the open command opens index.htmJ in your Mac OS X web 
brow.ser. You could also navigate lo this folder in the Finder and 
oi>en die file with a double click. 


The Coni iGURAiioN File 

Okay, now it Is lime to create your own dtx.'umemation. 
'Ihe first step is to gel a lemplate configuration file. When 
creating the sample project I created a folder called doxygen in 
the same folder as the projea file in the Rnder. I then moved to 
the new directory (widi a cd command) and then tyjx*d. 

%aoxygun £ return] 

like many UNIX ajmmands, using die command doxygen 
with the wrong nuinlief of aigumenis jirovides a brief stitement 
describing how to use the txjmmand. Unless you actually have a 
file called Doxyflle in die curreni directory, you will get a list of Lises 
for doxygen. 1 created a default temiilalc file (using the -g option). 

%doKyfile -g Fif;lt.doxycfg[n?Lurii] 

I do not use the default name Doxyfile because^ I like to be 
al>le to tell die associated [project from tiic configuration file’s 
name and by not naming my file Doxyfile, I tan use tlie doxygen 
command to get help. We now need to adjust the file lo suit our 
needs. You can edit the file in a Mac QS X text editor (such as 
Project Builder, AfphaX or BBEdit) or a UNIX text editor (such as 
emacSt vi or pico). Trying to describe which ciioice you should 
make is a can of woniis I will urn even try' to sort out here. For 
diose whtj are new to UNIX, I would suggest one of the Mac OS 
X editors listed above. You will lie able to open tlie file from the 
Rnder with a double-c:lick (once you set its Open with... field in 
the Get Info dialog) or from widiin the Open dialog of the 
application. Alternatively, you can use the command lie low to 
open the file with Project Builder from the shell (assuming Project 
Builder is in the location Apple filaced it). Tlie -a option allows you 
to sjKxify tlie application that will lie used to ojx‘n die file. If you 
find that you are doing a lot of opening w'iih the same application, 
chec k out the seaion lielow where I talk about the .teshre file. 

%Open -a /Developer/Applications7Project\ Builder.app 
Fisb.doxycfg[return 1 

The template file is heavily commented (unless you used 
the -s opuon when building i?) and is also descrilx?d in the 
doxygen documentation. I only adjusted the lines shown lielow 
for the sample project, 

FROJECT_NAWE - "About Box" 

OUTPUT„DIRECTOaY = ./doxyijen 
EXTRACT AU = TES 
EXTRACT^PRTVATE = YES 
EXTRACT_STAT1C = YES 
TAB SIZE “ A 

0FTTH1ZE_0UTFUT_F0R_C - YES 
INPUT = ./Source 
SOURCE_BROWSER = YES 
ALPHABETICAL,IMEX » YES 
GEKERATE.UTRX - NO 

The PROJECT_NAME line sets up a project name dial will be 
used in the documentation and die TAB_SIZE line indicates diat I 
use tabs that are four characters wide (since doxygen will convert 
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t:»bs to space?i when loniiatting the documentaiion). I al.so told 
doxygen that all source is C source (in the 
OPTIMIZE_OUTPUT_FOR^C line). Tlie SOURCE BROWSER line 
tells doxygen to include the source of the hies as part of the 
dcHiirnentatiori, I also requested an aiphaix:tical index of all of the 
com|x>und structures used with the ALPHABETICAL INDEX line. 

'ITie OLTTPUT^DIRECTORY line specifies where the output is 
to be placed. The directory caQed dot (J refers to ihe current 
directory and dot dot („) Ls the parent directory of dot (these are 
available in the shell so you can use them there aLw). To 
prepare for later work, 1 will assume that the t'urrenl directory is 
the directory containing the projec’i file (and the parent of the 
directory containing the t:on fig oration file). If you plan to 
execute the doxygen ctntunand from same direi'iory as the 
cam figuration file, then you might warn io use dot as the output 
directory. Thu GENERATE_LATEX line turns ofT the option to 
generate biTeX docuinentation (die template file creaies Ix^th 
HTMl, and UiTeX doeumentation, rtf and man documentation 
are available also hut turned off in tlie t cm n pi ate). The 
1NPUT_DIRECTORY spc'cirtcs where the header and soiircx: files 
reside. If you were planning to execute from within die same 
directory as the configuration file, you will need to change the 
input direaory to ../Source. 

Tlie three liners eoncerning EXTRACTion are telling doxygen 
ihai I want everything documented. If I wanted to hide 
iitiplementation details, I ccHild set the^se to NO and limit the 
visibilit)^ of the implenienlalions in the dcxrumentation. Toggling 
tliest" firovide you with cxjntrol over what is dixainienic’d and allow' 
yoti to create multiple sets of tkxajmenlalion, lor ex;tmpie, one set 
for petjple developing the [xickage (with these set to YES) and 
another for pcxiple who are u.sing the package (with these set to 
NO and maylie even the SOURCE.BROWSER also set to NO), If 
you want more derails alioui wiiai will Ik" extraaed, please consult 
the doxygen manual, however, there is one detail worth repeating 
hear. If you have EXTRACT_ALL set l,o NO, tiefitiitions within 
namesjraces ane only dcxiimenicxl if die namespace Ls documented 
Similarly, global definitions will only Ix" doaimenied if the file in 
which diey occur is dtx'umenteti (w'ith a @file tag). 

A good way to figure fiui whai doxygen can do is to poke 
arountl in the configuration file and to toggle some switc hes and 
compare die output. Although the configunidon file is long (over 
10(K) lines including comments), the comments help guide you 
through the various options. You can teest the configumiion file 
from the command line by first changing to the directory 
containing the pitijed file and ihen issLiing tlie command 

l&doxygen doxygen/ Fish * doxyef g f return! 

This should generate an hi ml folder inside the doxygen folder full 
of cloai mental ion that you can view with your browser. 

Preparing to DtixYtiENA^iE Your Code 

You can run doxygen without using any .special comments, 
however, you gel lietter results by adding them. This scaion is 


short because 1 found the iinnual and ex;tniples included with 
doxygen to lx: quite good anti suspect that the primary' obstacle 
to using it tin Mac OS X is going to be the installation process 
described above. Wliile reading the ex:imples here (and those 
provided with doxygen >, lie aware that doxygen is configurable, 
and if the comment style Ixdow feels unnatural to you, l:>e sure 
to read the doxygen manual to sec if your preferred comnieni 
style is .supported. 

To (ircpam your code so that doxygen can generate good 
dcKUmentation you will need lo place special comment hkx:ks 
inside your ctxle. There are a wide variety of options using both 
C and C++ style comments. I tend to use C++ siyfe comments (so 
iliat 1 can use C .style commenls to eliminate long blocks of c'odc 
during testing). If you preicr C style commenls, please refer to die 
doxygen manual for the ways they am be used (alone or in 
coniunction with C++ style commenls). When reading a source 
file, doxygen will recognize eoninienLs that begin with either /// or 
//! as a special comment that contains documental ion inldniiation. 
1 prcicT lo use III l^ecause it sticks out when I visually sain a file. 
You can structure the comments with a limited sulrset of HTML 
and by doxygen uigs (you can use either (§ or \ as the escape 
character, ! use @ liecause it sticks out wiicn I visually scan a 
fife). 1 have createtl a (somewiiai silly) !)rojeci to give you some 
idea of w^hat doxygen can do. I'he excerpt below is intended to 
provide you with a feel tor the tyjie of c'omments that can be 
added to the source to provide dtxiimentation. As usual in 
magazine printouts of code, watdi out for vvrap|>ed lines (or 
Ix^tter yet, kx>k at ihe actual .source file, available at the MacTech 
site iLH well as my website listed Ixilow). 

cxcapt fish.h 

//! #brlL+Tills stmcuia" informalii>n :iboui fish in rtiy fitc/jirT. 

m 

//! Jt iJcirsn't rtally tk> U> ihc- giv:ii uf things that arc ftsh 
//! in my frcc/er insuincejt might lie nice lu know how nld tlx7 arc or 
//' whether they s^til] liavc their heads, 
typedef struct 
i 

f ishTypes inyType: //!<wh:n lypc of fish wc arc dcsaihirig 
1 n t a^yWei |^hi: //kt he weigh r of the fish 

) fifih.t; 

//“ ^hrid'Hic number of fisti that fli in im freezer 

m 

//I Of i.'oursejt really depend-s on the size of Ulc fish and if 

//I I upgrade jiiy frcezi!r I will certainl)' need to ciiLtrgc this number. 

//\ TIjc <mly reason for all this rvi>ing is create a detailed descripUon. 

//define MAX FISH 10 

//! (fPhriefThe fish in my freezer, 
extern fieh^t freezer [KAX^FISH]; 

//I Wlirief Fills the frce/A’T with fish. 
voijd FillFreezerO: 

//! @bfief Retiinis ihc total weight of all fish of one type in tlie freezer 
inr Weigh(fIshTypes InType); 

excerpt frtnn feh.c 

//! This function itcratt*s thnnjgh all the fish m my freezer of 
//! a particular type and sums itp their weights. 

//! Tills function lepJaccs the tk^firtive Weigh FmO hmctitin. 

//! ^param inType b the type of fish 1 want to weigh. 

//I <5fivtum.s the total wci^dit of all fesh of thit type in my freezer. 

//! #biig 1 ran i figure out wliat's going wrong with this function, 
iret Weigh(fisbTypoE inType) 
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( 

int 1, reeuitj 

for (i Oi 1 < KAX_FISHe 1++) 

1 

if (freezerli).myType = ioType) 

-1 

result result + freezerlij-ayWeight; 

1 

I 

return result? 

1 

When processing; tfic code, doxygen will look for 
d(x:urncnLation for Idefines, Gnums, structs, global variables and 
functioas (and other tilings) ^ind will paxlnce lx)lh a brief 
description as well as a detailed descrif>tion. As a invention, 1 use 
the @brief lag for brief coinnients altiiough doxygen has a default 
algorithm for detennining the brief and detailed descriptions if you 
do not specify them. In the excerpt alxive, @parann indicates a 
pjimmeter to ihe function, ©returns describes the return value and 
a @bug lag adds iliis comment to die bug list (bonus question: CAn 
you find the bug’). If the comment ajotams .something lliai looks 
like a fiinction c^l) (for example, ilie WeighEmO alx>ve), doxygen 
will try to hyfXTlink it to die appropriate function’s dcxiimeniation. 
Anotlier nice feauire Is that doxygen will try tt> crosslink everytliing 
to anything referred to by it and anyiiiing to wliicli it refers, llie 
following is a text rendition of the documentation for the Funtiion 
Weigh(), 1 have indicated the hyperlinks with underlines. 

Siimptr lX>CLinirj]Utiiuu 

inr Weigh 
( 

flghTypefl 

InType 


Hetums the total weight of all fiah of one type in the 
freezer. 

This function iterates through all the fiah In jay rrcezer of 
a particular type and sunn up their weights. This furiciion 
replaces the defective Weig hEaf) function. 

Parameters; 

inType 

is the type of fish 1 want to weigh. 

Returns: 

the total weight of all fish of that type in my freezer. 
Bug: 

1 can'I figure out what Vs going wrong with this function. 
Definition at line M uf Tile Flah.c . 

References freezer . MAX FlijU . fish titayTy pe. and 


Referenced by main fI. 

You can find more samples in the doxygen examples as well 
as the projeti as.sociated with tliis article (at tlie Mad ech site as 
well AS my websiie fisted below). 

AnofNc; A DtiXYGEN Stage to Your Build 
I am going to leave further exploration of what doxygen 
does to the doxygen manual and examples and move on to 


ct>nLroiling doxygen from within Project Builder. 1 will describe 
liow I added a step to create the documentation at the end 
of the biiikl You t ouki place thi.s step at other points in the 
build process or even create a special target that generates 
documentation and nothing else. I selected tlie Edit 
Active Target 'Fish* menu item from the Project 
menu. In the left pane, 1 expanded Build Phases (well, not 
it was already expanded), and atlded a new build 
phase here by selecting the ResourceManager 
Resources item and then New Shell Script Build 
Phase in the New Build Phase submenu of tlie Project 
menu. There are two places I needed to add information. 
T'he first is the Shell: text field. This field is set to /bin/sh 
{The Bourne shell) by default. The Bourne shell is often used 
for scripts for portability reasons, but 1 want to use tesh for 
this project since our script is a simple single line command 
and I spend most of my time in tesh. To do this, I changed 
the /bin/sh to /bin/tesh. The second field is the command to 
be executed and in this case I typed doxygen 
doxygen/Fish.doxycfg. That wasn’t so tough. Now at the end 
of any successful build, doxygen will create a folder full of 
documentation (and doxygen’s me.ssagcs are sent to the Build 
window). If you just have a couple of simple commands to 
execute in the shell during a build, you can add them with 
separate iiheO Script Build Pha.ses. For more complicated 
steps, you might warn to actually write a file that contains the 
scTipi and then use the source command to execute that file 
from Project Builder. 

Doxygen and Dot 

When creating documentation, doxygen is al.st> able to 
generate diagrams describing variou.s relationships — in 
panicLilar, header inclusions and class hierarchies. In order to do 
this, doxygen needs to use an application railed dot. Ftist 
download dot for Mac OS X from the GraphViz website listed 
below in the references (my ct>py was version 1,10 built on 
08/27/2003). Tf working with the shell is still relatively new, you 
should grab the Installer package (whieli is what die instructions 
lielow assume beeau.se dial Ls what I did). Download it and 
install it according to die instructions, 1 W'ould suggest letting it 
place everything in the default lcx‘adt)n and die instructions 
below assume that you did iliis. If you place it somewhere else, 
you will need to do a few more steps (information can be found 
at the GraphVi^ website). You could check to .see if the files 
were installed with the following txMnmands. 

%cd / usr/local /bin[return] 

Xls dot [return] 
dpt 

When I asked the shell to Is dot, I am asking if to list every 
file c'alled dot and if dot does not exist you will get an error 
message. You c:an use * a.s a wildcard character, for example 

%ln *dot*[return 1 

dot dotligxl dotneatp-conf ig dotty gxlidot 
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Th\A is more amvenient than using Is I more in places where you 
know some part of the fiiemime. Now that you know the file 
exists, find out if tlie shell can Find the installation with which. 

%w)iicb dot I return I 
/usr/local/bita/dot 

In my case, everything is good. However, jtist like willi doxygen, 
it is likely that your experience was not quite so satisfying. 

%whlch dot[return] 
dot: Gonnimnd not found, 

The rehash commiind probably will not solve this problem. 
The problem is that the siiell (as set up i>y Apple) d<x^s not know 
that it should be searching in /usr/local/biny for comm^inds. Wc 
need to add some directories to the variable path. At startup, icsh 
wall read a nuinlx;r of files (/etc/csh,cshrc, /etc/csh,login and 
-/deshre. the - refers to your home directory). If you are 
interested in exactly when they are read, you should man tesh. 
A gcxxl place lo fiddle with your path is in -/.teshre, I am going 
to suggest you use pico to edit lire file since tliis Ls a simple 
ediiing job. More complicated files should probably be handled 
with more compliatted editors (like emacs, vi, AlphaX or BBEditK 
Notice that cd is the same as cd ^ (it will save you tw^o t:haracters 
of typing, which over your lifeiinie.., well, probably still won’l 
amount lo Ukj muclO, 

%cd[return] 

%plco -tcflhrc[return] 

'Hie pico editor is very simple and even provides you with 
rwo lines of commands at the lx>ttom of the screen. Here are 
some of the important lines that cxcur either in my /etc/eshJogin 
or my '-/.teshre files (watch ihe wrapping, there are three lines 
here, they start with set, setenv, alias). 

set patti ( Slpathl /usr/lucal/bin ) 

aotenv DYLD_LItiRARy„PATH /usr/iocal/iib/erapbviz 

alias alpha "'open ‘a /Applicatians/Alptaa/AlphaX.app*’ 

The set itne will add the /usr/locaI/bin/ direaory at the end 
of the search path for files, once this Ls added, Lite Icsh should 
lie aide to find dot. In order to lun, dot needs to deteniiine 
where its dynainicaliy loaded libraries are placed. 'Ihe setenv 
sets up the information in an environment variable so that dot 
will tx? able to Und this infonnatlon while it is running. The next 
line show how lo create aliases that on be used to open files in 
applications frimi the Terminal. In my ease, die command alpha 
is equivalent to open -a /Applications/Alpha/AlphaX.app. To opK-n 
.teshre in AlphaX, I can type the following command. 

Xaipha ^/.teshre 

Unfortunately, die open command does noi create a new 
file. If you want to create a file and then open it, one trick Ls lo 
first touch die file first (touch updates the last modification date 


of tlie File and if the file does not already exist, it will create die 
file). You c'an ase a semit'olon to pUic'e two cximmands on a 
single line. 

Itouch blah: alpha blah 

You need to add the first two lines to your .teshre file (tlie 
other line was provideti because it may lx? useful). Once you 
type these lines, save die d<Kliment by typing (control O, 
write Out) and hit Ireturn] to accept die filename. Tlien exit pico 
by lyping PX] {control X, eXir). You can cause die commands in 
diLs file to be executed by using the source command. 

%source .teshre 

Now, when you ask which dot die shell should find it (you 
changed the path variable so the shell aytomadcally executed 
rehash ft>r you). 

Xwhlch dot 
/usr/local/bin/dot 

Reojicn the Fish project and change the command in the 
Shell Script BuUd Phase to doxygen doxy9en/Fish2.doxycfg (notice 
the 2). The only difference berween Fish.doxycfg and 
Fish2.doxycfg is dial Rsh2.doxyctg has specified that we have dot 
(HAVE^DOT = YES) and that we wil! using gif style images 
(r>OTJMAGE_FOT(MAl' = giQ. Now rebuild the project and tlien 
browse the new documentation. 

Ck>NaAtSION & Bibuogkapiiy 
T he steps alnive have ftK'tised on getting doxygen 
installed, but many of the bits and pieces are common 
techniques for installing programs on UNIX systems. Although 
I have not had a chance to work with Xcode, I suspect that 
the experience will be very similar lo Project Builder. 
Hopefully you will take the time to try working with doxygen 
as well as finding other Mac OS X command line applications. 
If you find yourself using doxygen, please consider using the 
PayPal link from the doxygen website to show your 
apprecialkm. If you are really ambitious, doxygen can be 
extended to work with more languages than its cairrenl ones 
(it is open source). For example, an ambitious programmer 
could write code to support Objective C. 

Here are the sources I used Lo put logeiher this article as 
well as UELs mentioned in the article. 

• doxygen wel> site : www.doxygen.ofg/ 

• (}raphViz (dot) web site: www.phiLuu.nl/"‘js/graphviz/ 

• intrtKliKiion to tesh: Using esh & tesh by Paul DuBois 
(O'Reilly & Associates, Inc.) 

• my web site: www.cwu.eda/-fnontgoaa/ 

• MacTet'h web site: www.mactech.com/ 
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TOOLKIT 


hy Tim Monroe 

Strange Brew 


Running QuickTime for Java 
Applications on Windotvs 

Introduction 

In the two previous QuickTime Ttmlkii anicles (in MacTech, 
January and Fel>ruary^ 20(Vi), wc look a look at using Apple's 
QuickTime for java classes to build a simple Java-baseii 
Macintosh application that can manipulaie QuickTime movies. 
Our appliraiion — railed “JaVeez" — can o)>en movie Tiles and 
display llieir nu>vies in windows on the screen. Figure 1 shows 
a typical movie wintiow displayed by JaVeez. 



Figure /; A JctVix^z movie uimknv (Macmtosh} 

JaVeez supports all the standard editing operations on linear 
movies and can save edited movies intti their original files or into 
new fik‘s. If the user tries to close an edited movie file, JaVeez 
displays the dialog k)x shown in Figure 2, which gives the user 
the op|x>minity to save or discard those edits. 
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(Owi'tSwt } f CMCfl ) I 
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Figure 2: The Sate Changes dialog box (Macmtosb) 

In this article, I w'ant to invt'sttgiae wiiat needs to he done 
10 gel JaVeez to run on Windows u(>eraiing systems as well as on 
Mac OS X. In other wo ills, 1 warn to see how to turn the window 
in Figure 1 into the windtnv in lugure i. 


.siQija 

File Edit Movie Help 



Figure S’ A JaVeez movie tvimiow (Wiudou^) 


Ttra Mt>nrt>e is a iiieml>er of the QuickTiine engineering team at Apple. You can contact him at nnonrO€@inacT&chxom. The views expressed here are 
not neiessariiy shared l>y his employer. 
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And I want to see liow to tLim tite cJialog lx)x in Figure 2 into 
the similar dialog lx)x in Figure 4, 


FHe Edit Movie Help 


/ 


Save changes berore quitting 




Do you wand to save the changes you made to the document 
'‘Sampte.mov*? 


Sm 


cancel Don't Save 


QuickTime 



Figure 4: The Sain* Changes dialog box (Wimlouvi) 

The good news is that we dtm'l really need to do very 
much work at all to gel JaVeev. running on Windows, thanks 
to its Java underpinnings and to the plat[orm-iride|>endent 
graphical toolkits AWT and Swing- We need to add a small 
amount of pi at form-specific code to adjust the placement of 
the Quit and "About JaVee?/’ menu items, and we need to 
make a few adjustments to our Xcode project. But 
ultimately, and indeed fairly tjuickly, we'll have a single 
executable file that can be launched on both Mac OS X and 
Windows ('ompuiers. 

Once we've got JaVee/, running on Windows, we'll take 
a look at extending it on both platforms l>y allowing the user 
lo resize its movie windows. 'I'o do that, we'll need to install 
a movie controller action filler procedure. As we've had 
some trouble doing that with a few of tlic development 
environments weVe considered in recent ankles, it will be 
interesting lo see how' easy it is to do this using QuickTime 
for Java. 


Memis 

Let's Ix'gin by considering tlie code changes we neetl lo 
make to get JaVeez running properly on Windows, all i>f wliich 
are related lo the creation and handling of menus. On Mac OH 
X, the ‘^Alxmt JaVeez'' and Quit menu items are t*ontnined in the 
Application menir On Windows, those items need to be moved 
into the File menu ant! the Help menu, respectively. Figure 5 
sltows the File menu on Windijws. Notice that the Quit item is 
lalxled “Exit” on Windows, 
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9 Edit Movie Help 
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Figure 5‘ Ihe File menu of JaVeez (Windotm) 
Fij^rc 6 shows liic Help menu on Windc>ws. 
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About JaVeez 


QuickTime 




Figure 6: 'fhe Help menu ofJaVeez (Windows) 

First we need to erente the new menu and menu items; then we 
need to aiuicli actions to those new menu items. 

Creating Menus and Menu Items 

It’s easy entmgh to add a separator line and the Exit menu 
item to our existing File tnenu. The only mildly interesting hoop 
we need to jump through is to Rgure out whether JaVee?, is 
mnning on Macintosh or Windows. There are in fad at least 
three ways we can do this, 

Tlie standard way to check whether a Java application is 
running on Macintc^h is to look at the mrj,version pnjpeny, like this: 

If tSyatQin.geTProp(?rty(”jnrj .version"'} H null) 


stands tor ‘"Macintosh Knntime for Java’, which was the 
ofFtcial name of earlier versions of the java support on 
Macintosh computers. If the mrj.version properly exists, then 
the string object remrned by the System.getProperty metiK)d Ls 
non-null and hence our application is running on some version 
of Mac OS. 

While this way of determining dial our application is 
running on Mac OS is still sup|Kjrted in JS2E version 1.4,1 and 
later, it is no longer tlie recommended way of doing so. A better 
way is to look at the os.name property^ like ihis: 

if (System. getProperly {“os * name"). ciqua 1 sT gnoraCa so ( 

"Mac OS X")) 

lliis expression evaluates to true ju,si in case our application is 
running on some version of Mac OS X. 

Them is yet a third way to determine the current system our 
application is amning on, using the QTSession class we 
encountered in the two previous aaicles: 

1 f (QTSession, isCurrentOS tQTSeesion. kHacOSX) > 


We’ll use this third way throughout our application. For 
iastance, Listing 1 .shows the code well add to the 
addFileMenu Items method to add the Kxil menu item to the 
hoiiom of ihc File menu. 


Listing 1; Adding items to the File menu _ 

atidRleMeiiaItfun.s 

if {!(QTSession.isCurrentOS(QTSession,kHacOSX))) \ 
fileMenu,addSaparatorO i 

m.iExit = nev MenuItaiutresBundle* getSiringl^exitlcem'*)) r 
JiijExit.setShorTcut(nev KetiuShortcut(KeyEvent,VK_Qt 

false)): 

fileHenu.aadtsiiExit) .soLEtiablcd(tnifi): 
mlExit.addActionListenerCcxitActioid i 

1 


And Listing 2 .shows die complete revised version of the 
addMenus method. 


lisling 2: Coiiflgitriiig the menu bar 

addMenus 

public void () I 

ediiMonu = now Honii(rosBundlo.g^?tSttlrig(“6dltHeftu'’)): 
fileMenu = new MenufreaiBtLrjdlo.gotSTr ing(“fil oHottit")) : 
movieMenu ^ new Menu(resBundit*.getStringp'iiiovicMcnu")); 

addFiieMenuItemsO r 
addEditMenalternsO ; 
addMovieMeniirteniE (] j 

If C1 QTSession.IjsCurtentOSlOTSession.kHscOSX)) t 

helpMenu = new HenutresBundle.gerStr ifig(“helpMenu*'}); 
a ddHeipHenuit ems{): 


RetMenuBar {aiainKenuBar); 

f 


Tlie addHelpMenuitems metlKxl, which is called by this new 
version of addMenus, is defined in Li,sting 3, 
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; to 1^ Help menu 


aridHelpMcnultoins 

public void addriolpMenuIteuis () ( 

tnlAbout “ riEw MenuItem{resBuiidle. getString £ "^aboutltera")): 
lielpHenu.add(miAbout).aetEnablad(true): 
miAboutKaddActlonListenertaboutAction): 


mainMeimBaj:.add£helpMenu}; 

1 


Creating Actions 

AN thai remains is to detine two new action classes and to 
create instances of those two clas.ses {whicli, as we saw in 
listings 1 and 3, we add as listeners to the Exit and “Aljour 
JaVee^" menu items). Listing 4 shows how we can handle the 
Exit menu item on Windows. As you am .see, we simply c^^]l the 
existing method attempQuit, which inspects all open movie 
windows and gives the user the chince to save or discard any 
unsaved changes. 


Listing 4: Handling the Exit menu item (Windows) 

lixitAcUonCte 

public class ExltActiouClass extends AbstrattActian t 

public ExitActionCiass (String text. Keystroke shortcut) 1 
supec(text ): 

putValue(ACGELEKATOR_KEY, shortcut); 
t 

public void aciionPerforaied [ActionEveiit e) f 
cit LemplQui t (} : 

I 


Similarly, Listing 5 shows liow we can liandle the “About 
JaVee?:” menu item on Windows; again, we just c'all an existing 
inetlKxl, about. 

Limiting 5: Handling the About menu item (Windows) 

.\l>ouiAciionOass 

public class AboutActionClass extends AbstractActien I 
public AboutActionClass (String text) f 
super(text)r 

1 

public void actionPer formed (ActionEvent e) ( 
about 0; 


) 


operations. And selecting the “About JaVeez"' item displays the 
dialog bt>x shown in Figure 7. 



A QuickTime movie pl^r application 
built with QuicKTime for Java. 


^003 by Tim Monroe 


About JaVeez 


Figure 7; The About box of JaVeez (Windows) 

Note that wc haven't changed any of the cxxle called by the new 
actions. Our About Ixjx kxiks pretty much Uic same as Its 
Macintosh counterpart, thanks to tlie wonders of Java and Swing. 

Java Appucations 

Recall that we started building JaVeez by creating a new 
Xcode project based on the “Java AWT’ Applkation” tempLite. 
The target built l)y Xcode i.s a double-tdickable Macintosh 
application named JaVeez.app, This application responds 
appropriately to the basic Apple events OpenApplicacion, 
OpcnDocumcnls, and Quit Application. This means, in particular, 
that JaVeez automatically opens QuickTime movie files and 
Fkish files dropped onto its icon in the Finder or in the Dock. 

In fact JaVe 62 .app is just a directory that holds some special 
items. We can inspect those items by optioii’Clicking on the 
JaVeez icon and selecting the "Show Package Contents” item. A 
Finder window opens that holds a folder named Contents. The 
Contents folder contains a folder named Resources, which in 
turn contains a folder named Java. Figure 8 shows the contents 
of the Java folder^ 


Finally, we need to add a few lines of code to the 
createActions method to create instmee^ of these two classes; 
Listing 6 shows the c:txle we need to add. 


Listing 6: Creating actions 

crtatcAciiDns 

if (I(QTSession.isCurrentOS(QTSession.kMacOSX))) f 
exitAction new ExitActionClass{ 

resBundle.getString(*'exitltE?in’*), 

KeySt rokG,gctKcyStroket 

KeyKvent,VK„Q, shortcutKeyMask ))t 
aboutActlon new AbouLAcLicuiGlass( 

t e Ufid 1 e * ge t String (“ about Item'*)} i 



Figure 8: The JaVeez.jar file 


When tills is all dune, the File and Help menus will have 
the appearance showm earlier in Figures 3 and 6. Selecting the 
Exit menu item performs the standard application shutdown 


JaVeez.jar is zjam archm file, also called a jar file. It contaias 
the executable cxxle <3f the appltc^ation along with any images or 
otlier resources used by tlie application. Jar files are tlie standard 
dLstnbution containei^ for Java applicatioas, In tlreory, we sliould 
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[)e able to move this jar file to a Windows machine, double-click it, 
and have JaVeez launcth and njn. In practice, we need to make a 
couple of minor tweaks to our project for this to work correctly. 

Fixing the Manifest 

Indeed, dtjublc-clicking tliis existing JaVeezJar file won't 
even launch JaVeez on Mac OS X. If we try it, well see the 
warning shown in Figure 9 


While weVe here, let's adjust one other pmjecl setting, to 
prevent an annoying but harmless warning from being Issued 
each time we launch JaVeez. Select the “Cocoa Java-Specific" 
pane and wwcheck the ''Needs Java” tx)x, wliich Is shown in 

Figure 11, 


. .. . . 

1 1 

Jar Launthtr j 

! • 

Ttie jJtr file "JaVceeJar' covidn'i be lagnthed* * Check i 

the Console for possible error mess^es 1 

i 

1 

I 


Fi^ut'c 9‘ The launch warning 

'fhe Console log contains this message: 

Failed to load Main Class man!feat attribute from 
/Users/monroe/JaVeez/build/JaVeea. app/Contontis/Resotirces/ java/ 
JaVeez.jar 

The problem is that tlie default jar file's manifest (a special 
file in the arcliive that contains information about the other files 
in the archive) does not indicate which class in the jar file is ihe 
main class. To fix this, let’s add to the project a new file called 
JaVeez.mf that contains these lines: 

Main-Class: JaVaez 

(There is a newline character at the end of the first line; it needs 
to be theie in order for our new manildsl to work correctly.) 
Then we can set tliis file as tlie projeefs manifest file by 
specifying its name in the target settings panel, as showm in 
Figure 10. When we build JaVeez, the lines in the file JaVeez.mf 
will lx: apfxnded to the default manifest data. 


Figure 10: The Tnanifesi file seiiing 


Figure 11: Ihe '‘NeethJam''setting 

Leaving that setting at its default value wall result in this warning 
appearing on the console whenever we launch JaVeez: 

• [NSJavaVirtualMachlne itilLWltbClasspath:] cannot 

inalantiate a Java virtual machine: 

Ui’s rebuild JaVeez so ihai these c:hanges take effect. Now 
double-clicking the jar file will latinch the application, as 
desired. Tliat's very cool. What's perhaps not so cool is that 
when we launch JaVeez by double-clicking the JaVeez.jar file, 
we lose the Finder interaciion we got when we kiundied it by 
double-clicking the JaVeez.app file; in particular^ we can't drop 
files onto the JaVeez.jar tile or into its Dex-k icon. 

Adding Stub Classes 

Can we now' move the jar file tti a Windows machine and 
run it? N()i (juite, but almost. Recall iliai JaVeez uses the 
Application class in the com.apple.eawt package to handle the 
basic application-related Apple events. This package is not 
imptemented on Windows, so we need Ky do a little l)iL of wcjrk 
to keep the Windows Java runtime engine ha[>py. 

Jliere are several ways to work around this issue. The 
easiest way is to add ,some ,stub classes to cjur project diat 
provide empty implemeniations of the classes and methods in 
com.appJe,eawt. Fortunately, Apple provides a set of stubs that 
can lx: used for this purpose. I.ot>k for the sample ctxle 
package called AppleJavaExtensions on the Apple developer 
site* This package consists of a file called 
AppleJavaExtensions.jar. We need to unpack that jar file; in a 
Terminal window, execLUe this command: 

jat -5tf AppleJavaExtensions.jat 
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Wlicn this command completes successfully, you'll see two new 
directories named META-INF and com. Copy die com directtjiy 
into the JaVeez folder that contains the application project files 
and source code. Add that folder to ihc project the project file 
now looks like Figure 12* 

® 0 B .. ^ JiVfRx ., O . 



Figure 12: The afniaied projeci file 

Hiiild the project and copy the JaVeez.jar file to a computer 
running Windows that has Java and QuickTime installed on it. 
Double-click die jar file and behold die new empty movie 
window that appears (Figure 13). 



Figure IJ: An empty rnotne window (Windows) 

Use the Open menu item in the File menu to open a 
QuickTime movie file and then spend a few^ minutes verifying 
that the movie and its windtjw lidiavc as expected. (Sec 
Figure 3 again.) 

let’s paiLse to consider our progress so far. We now have a 
fully-fLinctional Windows appikraiion, and wc did dial with just 
a couple of easy adjustments to our existing project and source 
code. We added some code to handle die different locations of 
lire Quit/Exit and About menu items on Mac and Windows, and 
we tweaked the jar file’s manifest to specify the application's 
main class. Also, we added a few stub classes to our projea to 
provide empty implementations of the com.apple.eawt package 
for W^ixidows. Every tiling runs fiiie. We’re done, right? 

Using Reflection 

Wrong. To lie honest, Fd be very Impjiy to consider our 
jiorting work done, and dien move on to add some features to 
JaVeez thai show off the interesting capabilities of QuickTime for 
java. Alter all. we da now have a single jar file that runs on both 
Mac OS X and Windows and that has all the features we 
originally planned. But in fact weTe not quite finished. Ihe 
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reason is that the styb-class solution descril^ed above, though 
technically impeccable in terras of getting the job done, has a 
decidedly non-Java flavor. The generally-preferred solution Lo 
the problem of classes l>eing implemented on one platform but 
not on another is to use a feature of the Java language known 
as mfleciion. Tf you're liappy using the stub elasses, skip Lo the 
next section, Otheiivise, read on..,, 

Here's the crux of the issue: JaVeez currently contains the 
following line of ctxle, which creates an instanc:e of the 
com,apple,eavvt,ApplicationAclapter cbss and aiuiches it to lAppltcation, 

f ApplicatioD, addAppllcatioiiListener ( 

new cotn.appie.eawt .ApplicationAdapterO ( 

When the Java amtime engine loads a package, it looks for all 
c:]asses referenced in the pat:kage. Even though this line (if code 
won't actuiilly be executed on Windows, the runtime loader .still 
wants to find some code for the ApplicationAdapter class. 

Rather than solve this problem by providing no-op 
implementatioas of tlic classes in com.apple.eawt, w^iicli is what 
the stub classes provide, we can factor the relevant code into a 
new package and then load that package only if JaVeez is 
running on Mac OS X. Tlie Windows riintinic engine never sees 
the references to com.apple.eawt, so the stubs are no longer 
necessary. Very nice. 

Let’s Ix^gin t>y defining a new package, called "osxadapter", 
which imports the com.apple.eawt classes and the JaVeez 
application classe^s: 

package osxadapter; 

impor t com.apple,aawt : 
import javeea.*; 

the osxadapter package contains a single class, OSXAdapter, 
which defines three public methods: handleAbout, handeQuit, 
and registerMacOSXApplfcation. (The code upon whicli this class 
is based defines two additional methods for liandling an 
applicaLi{)n's preferences; since JaVeez does not support user- 
selectable preferences. I've taken tlie liberty c^f removing those 
methods.) Listing 7 shows the complete definition of the 
OSXAdapter class. 

Listing 7t Handling Application menu items 

OSXAdiiplfT 

public class OSXAdapter extends ApplicationAdapter I 
private static OSXAdapter theAdapter: 
private static cotn.apple.eawt.Application 

theApplication: 

private JaVeej! niaitiApp: 

private OSXAdapter (JaVeez inApp) \ 
tnalnApp = inApp: 

I 

// handle the About menu item 

public void handleAbout (ApplicatiouEvent ae) [ 
if {malnApp 1“ null) f 
ae.setHatidled(true): 
mlnApp,about(): 

1 else ( 

throw new IllegalStateEKceptlcin('TandleAbout: JaVeez 


instance detached t’rora listener"): 

1 

// handle the Quit menu item 

public void handloQuit (ApplIcationRvertt ae) I 
if (mainApp 1“ null) [ 
ae.setHandled(false): 
mainApp, attenrptQult (): 

I else I 

throw new riIegalStateException{“handleQuit: JaVeez 
instance detached from listener*"); 

) 

I 

public static void reglstetMacOSXAppllcatlon (JaVeez InApp) t 
if (theApplication = null) I 

theApplication = new ccin!.apple.eawt.Appiication(); 

) 

If (theAdapter = null) ( 

theAdapter = new OSXAdapter(inApp)i 


theApplication,addApplicationListener{theAdapter}s 

1 

t 

llie first two methods, handleAbout and handleQuit, simply 
call the existing about and attemptQuit methexis in JaVeez. They 
also lx)tli call the setHandled method of the AppItcatlonEvent class 
to indicate whether or not the event has been handled. Notice 
that handleQuit needs to pass false to setHandled since we want 
to allow ilie LLser to cancel the application .sliut-down operation. 

The interesting method in the OSXAdapter class is 
registerMacOSXApplication, which creates an Instance of the 
Application clas.s, c:reaies an instance of tlie OSXAdapter class, and 
then adds the adapter object as a ILstener for the Application 
oliject. llie registerMacOSXApplication method is the only 
methcxl that JaVeez needs to call explicitly at run-time. Of course 
JaVeez cannot invoke that iiictliod by name (since it references 
classes that do not exist on Window^s machines); rather, it 
invokes that mcihod indirectly, using Java's reflection APIs, 
listing 8 sliows the definition of the macOSXRegistration 
metlKxl rliat we need to add to JaVeez. 


Listing 8: Registering a Mac OS X application 

macOSXRegistraUon 

public void macQSXKcgistration () I 

if (QTSeaslon, isCurrentesCQTSessiiOTii.kMscOSX)) [ 
try [ 

Class ouxAdaptar = 

Class.forName{"osxadapter.OSXAdapter”); 

Glass(] defArgs * fJaVeez.class): 

M&thod register Method ^ 

□sxAdapter.getDeciaredMethod( 

“registerMacOSXApplication", defArgs): 
if (cegisterMetbod != null] [ 

Object [] args “ I this): 

registerMethod. invoku (osxAdapLei:, args]; 

1 

1 catch (Exception e) f 
e.printStackTracet): 

} 

[ 

] 

As you can see, macOSXRegistration calls ClassJorName to find 
tlie class named "OSXAdapter" in the package osxadapter. If it 
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finds ii, macOSXRegistration executes that methml by culling llic 
invoke method. 

Callback Procfditkks 

ik> JaVeex now njns on both Macintosh and Windows 
computers. We can open t>ne or more QuickTime movies, play 
them [jack or interact with tliem, edit them, and save or disc;trd 
those edits as desired. JaVeez currently meets or exceeds all our 
original requirements, using nt)Lhing more tliuii standaril Java or 
QuickTime for Java classes and methods. 

Let’s consider briefly how to extend JaVeez, In particular, 
let’s see how to install a movie controller action filter procedure 
to receive anti re.s|xmd u> movie controller actioas. For the 
moment. wcJl handle only the mcActionGontrollerSizeChanged 
action, which lets us know that the controller has clianged size. 
Well use that action to su(>jxm resizing of movie windows. 

Resizing Movie Windows 

You may recall frf>m our first article on Java and QuickTime 
that we initially configured our movie windows so that they 
cannot lie resized by the user; we did that by adding this line of 
exxie to the JaVeez class consirutior: 

setReai?.ahlc(falflQ); 

Now you might think that part of wliat we need to dt) in order 
lo alkjw rc.sizable windows is la change that false to true. 
Unfortunately, doing that would lead to problejus, becattse AWT 
would want to draw its own grtjw box in the lower’right comer 
of a m(jvie window, iis shown in Figure 14. 


0 O 0 SampleMovte,mov 



Figure 14: A moi^ie mruiow with the AWf grow itox 

Insteatl, we want to use the grow Ixjx provided by Uie 
QuickTime movie controller, which you can see in Figure 15 


® 0 © Sampl€Movi€,mov 



Figure IS: A mwie window uHth the mopie controllergn}W fnxx 

To accomplish this, we ll continue to pass false in tiie call to 
setResizable, We'll get the movie comroller lo draw its grow tx)x 
in the standard way, by defining a non-empt)’ grow box 
reclaiigle. In tlie createNewMovieFromFile method, well execute 
these lines of code: 

CJUKect reel ’ new QDRent(IJJOOO, 12000): 
me. setCrowBoxBouiida {rec t) i 

Once we've done this, the movie ct>ntrt)ller will draw the grow 
lx)x in the appropriate location and allow' the user to resize a 
movie by click-dragging in that lx)x, 

Handling Movie Controller Actions 

Nt)w we need to resize the Java frame (tlxit is, window) 
when the user resizes the movie using the grtm' Ik)X. As usual, 
we do this by suitably responding to the 
mcActionControllerSizeChanged action. F’irst, we need to define a 
movie controller adion filter method. Listing 9 shows the code 
well add to JaVeez. 

Listing 9; Defining a movie controllcT actit»n filter method 

execute 

public class MCActlonFilter extends ActioTiTilter ( 

public boolean execute (HovieConttoller me, ini action) I 
if (action == 

StdQTCnrjfltantJt.tisrAci'ionControl lerSlzeChanged) f 

pack{); 

I 

return false: 

I 

I 

As you can sc-c, we simply call the pack metliod when we 
receive the appropriate action. We also need to implement the 
getPreferredSize method, which is c:allL‘d by pack. Listing 10 
shows our getPreferredSize mcihcxl. 
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Listing 10: Setting the size of a movie wind ow 


l>ublic Dimension getPreferr^Slze () I 
Dimension franteOiiit • new Dlittenslon(0* G) r 


try I 

QOEect rect - m^g^tBoxO i 

if (iic.getVieibleO) 
rect “ nc.aetlounds(}; 


// miktr stilts I hat ihc movie lia^i a non ^tefo widlU; 

// a /A'm hiighi is okay (for txanipk, wiiJi a itnisic movie with no controller 
l^r) 

If (rect, getWldthO “ 0) 

rect.setWidth{this,getSl?,e() .width) r 

// reslee die frame to the e:alciilatetl si7je, phis window horders 
ftameDlm.setSI 5tG{ 

reel .getWIdthO + {getlnsetsO ,ieft t 

getlnsetsO .right). 
reet,getHeight () ^ (getlnsetsO .top 

getlnsetsO -bottom)) i 

I catch (QTException err) 1 
err.printStackTrflceO ; 

I 

return(ftsmeDitn): 

* 


Thcrcs nothing much new here. In ha, this metlicxJ i^^ 
based on tlie sizeWindowToMovie methtxl that appeared in tlie 
hrsf aniele in this series. Using getPreferredSize is by far Ix:rrer 
Java code. 

Finally, we need to insiafi the action filter method, like this: 
iDc .setActlonFilter (new HCActionFlXterO ♦ false); 


With these changes, the movie windows displayed by jaVeez 
should resize as expected. 

Conclusion 

QuickTime for Java provides a very nice set of capabilities 
for building QuickTime applications with java. The support for 
displaying and controlling movies using movie controller 
components is extensive and easy to use. And, as weVe st^en 
in detail in this article, it's extremely easy to write our 
applications in such a way that ihey are easily ponable to 
Windows computers running QuickTime and Java. Whether we 
use Java's relied ion APIs or resort to the stub classes, we can 
get our X application running m Window.s in a matter of 
minutes. Cross-platform pojiabiJity is of course one of the key 
promises of Java, and it's refreshing to see that promise 
realized so fully in this case. 
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Mailsmith 2.1 


E-mail client for control freaks 


iNTRODlJtn’ION 

If 1 were writing this review for Macliome, or even 
MacWofid, Td spend time talking about how smart and user- 
friendly Mailsmith is. I would go out of my way to claim that it 
isn’t just for power users, prognimmers, hackers and geeks, lliis 
would be true. It's not. 

But 1 am writing this article for MacTech. You are a MacTecit 
reiider. I am going to make the not unreasonaiile assLim]‘)tion that 
you am a [xiwer user, [>rogranimer, liacker and/or geek, that you 
are, in short, a control fre;ik. Bare leones, developer and publisher 
of Mailsmith, de,s('rilx^,s it as an e-mail client written by M;ic useis 
for Mac ttsers. T want to descrti’H? it more aggressively, as an e-mail 
client written by control freaks for control freaks, like you. 

1 am also going to assume that you are ntx already using 
Mailsmiili, and that you imiy need more than just a nindown of 
what’s new in 2,x. Now there Ls a lortliat’s new. In fan, in versions 
2.0 (released fall 2003) and 2.1 (released January 2CK)4), in addition 
to hundreds of prolilem fixes. Bare Bones added liundreds of new 
features or feature enhancemeoLs, including i^GV support, 
coasiderably enhanced integration with OS X, native sup[x>rt for 
SpamSieve, greatly improved notification optioas (even support 
for Lite Griffin PowerMate), dianges to the tlefault mailfxix 
structure, and much more. If you want all the details, you am get 
them from Bare Bones' wet) site. But in tliis review, 1 am not going 
to liKus on what's new. I'm going to Focus on liow yt>u, tile 
power user, can m;ike Mailsmith do your I lidding. 

Customize! 

Let me start by noting tliat there's a lot you can do to 
customize the way Mailsmith ItKiks, Iiow it works, and how you 
interact witli tL There are different ways to view mail ILsts and 
messages. You can change fonts, font colors, and font sizes for 
lists, for reading me.ssages, firr composing messages, for 
printing. Window size, text wrap on/off, where your favorite 
AppleScTipt editor is located, a slew of options relating to sfxiio, 
attribution line for text quoted in replies—^ytiu c-an c'ontrol all 


these, and more. What 1 particularly like is the ability to add or 
edit your own keyboard shortcuts, not just for every command 
in the menus, bin also for palette itetns such as glossaries, 
stationery, and scripts. I touch my mouse very little when I’m 
working in MaLlsmitli. 

GEniwG AND Sending 

One option Mailsmitli does nt>t give you: TMAR Bare Bones 
says that IMAP support is cm the li.si for a future version. But, at 
the moment, Mailsmitli is aimed at the niner^^-plus percent of its 
that don’t need IMAP. 


* ^ O ACCO M nts 

[ ittw.,. I ^ Otiwe ] AcUHIfil Ntntt: | 

i 
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1117 n I 
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Polytrepe I Suppoft 
Palytr^pC 4 FSA 
Poiytropc S UsU 


DrcdcNow 




fi^fure L Wc advanced lah in the accounts dialog, 

rha! said, Mailsmith 2d gives you a lot of control over your 
POi^ and SMTI^ atx'ounls. You can, of course, have as many 
different user accounts as you like, each independently 
configured. Username.s anti pa.sswords can l>e stored in the OS 
X Keychain. Version 2.x adds a iiumlxrr of valuable new 
features, including secure (SSL) connections, SMTP 
authentication, the ability to delete messages from the seiver 
after m rbiys, faster uploading and downloatling, improved 


WilUaiii Porter, PIkD., a fomier professor of (Classics and Honors at the Llniverslly ol' Houston, now spend.s most of his time doing c-nM, or builciing 
databases. He Ls the owner of Polytrope, LLC, an inde[x?ndent database development firm in Da this, Texas, i ie lia.s written for MacTech in die past 
ulXHit 4V), and FileMaker Pro. He reviewed Mailsmith 1.5 in 2002 for TidTiits, and later wrote the chapter on filtering in the Miiilsrnitli 2.0 user manual. 
You can reaeli liim ai wp@poiytrope,com. 
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handling of signatures, and more. (See Figure 1. ) If you l^ve 
PGP 8 or liigher institlledj Mailsmith 2 added the ability to 
ciyptograpliically sign oulgoing messages. The POP Monitor, 
improved in version 2, lets you view messages directly on the 
server and get them or delete them. 

By defauU now, Mailsmilh 2 uses the OS X Address l^)ok to 
store e-mail addresses. Integration with the Address Book is so 
smooth, it's nearly invisible, 

HTML AND “EnRICHH) TJiXI ” 

Mailsmith does not display “entiched text," that is, font and 
simtde [>aragrapli formatting tfiat may have b<^en atided tt) a 
message that was written in a program such as Apple’s OS X 
Mail. If someone sends you an enriched-text message, Mailsmith 
will display it as plain texL 

On the other hand, Mailsmith does support full-blown, 
properly formed HI'ML messages, 'lb be sure, it does not 
enamragc HTML e-mail. If your mail consists largely of spam, 
or if the majority of your correspondence is with people wlio 
can’t express themselves adequately in a single font, well, 
Mailsmith might not be the besi choice for yoit. Rut if all you 
need to do is view the occasional stray piece of non-spam 
HTML mail, Mailsmith can do it fine, First, it does a great job 
of extracting the non-HTML content from messages and 
displaying this in the message window, Tliis lets you see what 
the message is about without actually having to see what the 
message ts about, if you gel my drift. And if you decide you 
need to see the message in all its decorated splcndt>r, you 
simply dick a button, and Mailsmith passes the message to 
your defaull web browser. Mailsmith 2.1 integrates beautifully 
with Safari in OS X vlO.3 (Panther). 

I can’t help noticing that BBEdit 7.1 now offers HTML 
preview right inside the app. Is sfanething like this in Mailsmith’s 
future? I do not have any inside knowledge, but I doubt it. IPs 
nor hard to switch to a real browser, and you would need to do 
this anyway if the HTML message being rendered mntains 
clickable links to other web pages. And in any ease, MaiJsmiiJi 
was obviotLsly designed by and for people who ^>eiteve that e- 
mail sliould [)e plain text. 

IITML aside, Mailsmitli displays photas and even movies fine, 
not inline, but right in tlie program, via mtegmiion witli QuickTime. 

Text Eduung Heaven 

1 remember that, when i first saw' Mailsmith version 1.0, 
I thought it was little more than HBEdit with POP and SMTP 
support racked on. Even then, lIuiL was both unfair, and 
unobservant. But ironically, while I have come to appreciate 
flow deep Mai I smith’s feature set truly is, I've also decided 
that Mail smith’s text-handling looLs are among its very 
strongest features. This is an e-mail client for users who 
write a lot. 


Font & Tabs.., 


Balance 

Exchange Characters 
Change Case... 

Change Case 

^C 

Shift Left One Space 


Shift Right One Space 

CfW] 

Hard Wrap . , 

Add Line Breaks 


Remove Lme Breaks 


Rewrap Quoted Text... 

n' 

Increase Quote Level 

xm 

Decrease Quote Level 
Strip Quotes 

xni 

Zap GreinJins... 

Entab... 

Detab... 


Resolve URL 


Check Spelling... 

nfiz 


Figuf^ 2. Maiismitb*s Text menu, showing the 
atray of text-editing optiom. Look/amiitarf' 
fPs identkal to BBEdiPs Text menu. 

When I have to use another mail client, whether it’s Apple’s 
OS X Mail, or Eudora, the web nKiil app on .Mac or .something 
else, the thing 1 miss the most about Mallsmidi is the rich set of 
com|>o.siLional options it provides. Heck, I miss these UjoI.s even 
when Pm working in my favorite word processor, Mellel In 
adtiirion to tlie options shown in Figure 2, Mailsmith provides 
multiple diplxxards, unlimited undos (and redos), commands 
that let you insert a list of a folder’s contents, or a file path. 
Mailsmith makes it easy to define, and use stationery in your 
conesfxjndence, diiio for signatures. 

Best of all, Mailsmitli gives you the .'^me jxiwerful glas,Siiry 
feaaire that BBEdit lias. For starters, die glossary feiiture lets you 
store, retrieve, and insert hits of reusable text. I use glossaries to .stom 
a lot of die tilings I need to say over and ovct again in my 
correspondence with clients: instnictions on updating solutions, 
downloading files From our server, etc.. But, Mailsmitli gkxssaries can 
go lieyond inserting static text tlirougli die use of ''placeholders." 
Some placeholders aie simply variables that will be replaced by die 
current date, time, or username. Some placeholders lei you 
manipulate text. For example, I use this gkxssary with die #8ELECT# 
pkic'eholder to put angled bmekets around a selected URL; 

<#SFJ.KCT#) 

I .select the URL, then type option-command-U. (That's the 
keylxiard shortcut IVe defined for this glossary). Finally, some 
placeholders can actually trigger caladations. Tlie “^SCRIPT 
scrijnnameir** placeholder that run.s the .script named as a 
parameter when the glossary is pixKessed. And the “^^'^SYS'TEM 
commundtt” placeholder lets you send Unix commands to your 
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dcfiiuit shell when the gkjssary is processed! Tlie SCRIPT and 
SYSTEM placeholders iBust return text values, or values that can 
be coerced to text; the v^altie returned is inserted into the 
message where tiie placeholder was originally. 

I'm going to pass quickly over one of Mailsniith's most 
powerful text-processing feanires, namely, its find-and-replace 
feature, which, like the same feature in PBEdit, gives you all the 
pov^cT of regular expressions (grep). I use grep in BBEdit fairly 
often to nrassage large sets of raw data, 1 have found that 1 dcan't 
use it very often in Mailsmith, 

By the way, Mailsmilh provides tools for manipulating text in 
inconting messiiges as well. Ever get a menage that's l:jeen 
forw^arded two or three rimes and has gotten horribly 
misforfiiaited? You can’t save edits to incoming mail, but you can 
clean up fonnatting disiistei's in two seconds to make messages 
easier to read. Get mail lists in digest format? Mailsmirh 2 will now 
extracn and disf)lay the individtial messages for you, and yem don't 
need to use a plug-in. And while some might criticize Mailsniith's 
user interhice as austere, those of us wlio love the program see the 
same iliing, bin regard it as a virtue. I prefer to dcscrilx/ it as 
uncluttered, and elegant. It’s a great environment for leading, 
dhere’s something grown-up alxrnt it. By contrast, wlien 1 cianlt 
tip Mail, 1 always feci like I’m in ihe Or. Seuss .sctiion of ilie literary. 

Message ManagelMent 

lliose who write a lot of e-mail lent! lo gel a lot in return. 
Mailsmilh hel[is you manage your mail store with |X)wer, 
intelligence, and efficiency. There are .scores of nice features to 
ihe iLser interface that make a difference here. Mailsmilh gives 
you a couple different ways to view your mail (eidler using a 
unified three-pane browser, or using a se[iarate window for 
every maillx)x}. Contextual menus provide access to most of the 
commands that can be applied to a me.ssage .selecned in a list. 
Messages can Ix" moved ""manuatly" from one maill:H)x to 
anotlier entirely ftoni the keylxiard. But, the three keys to 
controlling your messages in Mailsmith are fillers, advanced 
queries, and its !iuilt-in .sup|)on for Michael Tsai’s SpamSieve, 

Since IVe written alxiut Mailsmith’s filters at length 
elsewhere, HI re.strict myself here to the executive summary: 
MaiLsmith's filtering options are without equal. Mailsmith filtei:s 
can have as many critena as you like, and the criteria can lx as 
simple, or as sophisticated, as you like—-almost anything is 
p(),ssihlc, from finding mes.sagcs from your mother, to grep 
pattern tiiatching. filters can also have multiple actions, such as 
applying a label to a message, moving the message ro a folder, 
sending an a u tom a lie reply, or mnning an Ap[)leScri[rt script. 
And, since filters can 1.x attached not just to die Incoming 
mailbox, but to any mailbox, they can be triggered automatically 
w'hcncvLT a me.ssage is moved, something not possible in other 
j>rograms. My sense is that die dc.signers of Applets OS X Mail 
believe that users are not going to l'M:>lher with filters; that's why 
filters have Ixen stuck away in the preferences dialog. In 
Mailsmilh, however, Hlters are front and center. In fact, there are 
three quite distinct ways to define filters, all ready to hand. 


Mailsmith’s simple query command is great for finding 
messages in the current mailbox from senders whose name 
indude "Bob". But the advanced (juery (‘omtrrand can find 
alniosi anydiing. Actually, die advanced query dialog is nearly 
identical to the criterion pan of the filter-definition dialog, but 
you may flnti yourself using different aspects of the dialog in 
queries than you use in Oilers. I don’t liiive any filters that test 
for date.s, but I query on dates ftiirly often. The advanced query 
feature has two signific:ant limitations. You cannot tell Mailsmilh 
to search within multiple, non-nested mailboxes (something you 
can do in Eudom). And, advanced queries cannot be saved. 

I used to ftlrer incoming messages very aggressively a.s s(X)n as 
they arrived, and Mailsmith 2 will filler messages into a|)j)ropriate 
maiitx>xes, llten open maiilx^xes Utat have new mail But nowadays 
j let inarming messages sit in the incoming mailbox, so I am read 
them all in one place. If I need to find a ifiread,! use tlic advanced 
qtieiy dialog (or a script) to do so. When I’m done reading, I apply 
manually. 1 let filters autonruitically delete list messages that I 
haven’t marked for keeping, 1 used to have lot.s of individualized 
inaillx>xes with limited numlxis of messages. Now 1 find it easier 
to deal with fewer, fatter maiil.xjxes. Ibe change in my M.O. reflects 
the fact that the advaoccxl query aimmand has become a routine 
pan of my interaction witli tlic application. 

rinafiy, of course, there’s the headaclx of spam. Apple Mail 
li;ts 2 |X)werfiil .spam filtering feature built-in. Mast other OS X e- 
mai! clients can usc‘ Michael Tsai's SpamSieve scripts to acliieve a 
very .similar degree of success, llie great tiling alx>ut SpamSieve is 
that you train it yourself, and you control every aspect of its 
openiiion. And SfxiniSicve, like Mailsmilh, is hrilliantly integrated 
with OS X. You can, for example, use your Addiess Book as a white 
list. The smart developers at Bare Ikjnes, recognizing that 
SpamSieve was a winner, decided that the Ixsl thing diey ecjuld do 
was provide native support for it in MaiLsinitli, so that is what tliey 
did. This gives Mailsmitli the advimtage over the non-Apple 
a>mpetit3ctn, Ixxause SpamSieve d(K.'sn’! need scripts Lo work in 
Mailsmith, and also Ixcause it can find, and remove spam before 
any flltejing is done on your messages. SpaniSiev^e lias die ugliest 
icon in my Dtxk, but doggone it, it is effective. It catches cl<xse to 
lfK)'i4j of my spam, witli just one false [Xjsitive in die last six months. 

FINAI.IY, APPIFSCRTET 

like BBEdil, Mailsmith provides deep, and extensive 
.sLipport for AppleStTipt. You want control? AppleScript gives it 
to you. You can, in essence, create your own meta-app with 
AppleScript to make Mailsmith jump through htK)ps. 

Mailsmith is both recordable, and attachable. Recordability 
works great sometimes. I wanted to write a little script to sefed 
text from the insertion point to the end of itie sentence* I turned 
“Record" on in the Scripts menu, opened the Find definition 
dialog, enabled grep, and tyj^ed in a simple regex that finds the 
next period or other common sentence terminator. Exeatted the 
find, then stopped recording, Hci'c’s wliat was generated; 

tell application “Mailsmith" 
activate 

find "[\\,V\l\\i\\?\Vr]" searching in text 1 of message 
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window 1 options [search mode:grap, starting at 
toptfalse* wrap aroundrfalsa» backwardsrfalse, case 
sensitive:false* match words:false, extend 
selection:truei with selecting inatch 

end tell 

Worked peifectly. Note the itse of bac'k,s|jifih c:haraclen>, 
TIk* second esca|ies the reserved character that follows it 
and tile others), and is required by Mailsniith. The first 
“\”escapes the second, and is required by AppleScrtpL 

Now, recording doc,s not always work this well, but many 
of the kinds of things 1 personally want to do with AppleScript 
are child's play. Here, for example, is my "^ciui!" script, triggered 
wlicn I type' C(jrnrnand-Q. (Yes, I’ve reassigned the keylxsard 
shortcut to this script.) 

tell application "SpamSieve" 
activate 
quit 

end tell 

tell application "Mailsmith” 
activate 
quii 

end tell 

By the time you read diis review, Bare Bones may have fixed the 
bug that makes it currently impossible to attach a script to the 
Quit command in the Mailsmith meniL When tlrat l>ug is fixed, 
r1l get rid t)f the second part of the script alxive, and attach this 
script to the quit command directly, 'llien it will be run 
regardless of whether I type Command-Q or invoke the quit 
command from the menu, 

] mentioned alxwe that you can’t save atlvancetl queries; you 
can, however, .script them. AppleScript is a great w'ay to Oil in liie 
raic‘ gai>s in Mailsmitii’s feature set. Mere, for example, is a script i 
picked up from am>ther user, and adapted just a bit. 'Ihe stTipt 
finds mes.sages that have the same siihjetl as a seletied message. 

tell application “Mailsndth" 

try 

set aienaage_l lat to selection as list 
yeL Lhe_iEGfiaagG Lo iLem 1 of measage^llGr 
cjet the_cuntEdner Lu conLalner of llie„iDCSsagC 
set the_5ubject to subject of the_niessage 
if tbe_5Ul>jecT starts with “Re: “ then 

set the^count to count characters of the_subject 
set the_subject to characters 5 thru the_count “* 
of the subject as text 
end if 

set Lhc^namc to "Thread: " h the_si3bject as text 
juake new until list window with data every meaGagc 
of the^container whose subject contains Lhe_subjecL 
with properties [name:the_name) 
end try 
end tell 

This script comjDcnsates for MailsmitlTs lack of a true 
threading feaaire. By compari.soap Apple's OS X Mail does have 
a nifty ihrcading feature, l>ut it hardly compensates for the many 
serious limitations in Mail’s support for AppleScript. 

If you are already an AppleScript adept, you are going to 
love w^hai you can do wiih Mailsmitiv. And if you're nou^ Well, 
neitlier am T But as 1 suggested above, there’s a great deal you 
can do with very simple scripts, and many more complicated 
scripts can be Ixirrnw'ed. And, Mailsmiifi may inspire you to 


learn more. Malt Neu berg's new !x)ok on AppleScript is my 
niglitly reading these days. My iiojx^ is someday soon to write 
an AppleScript that will not only get my mail, and read it for me, 
l^ut draft and send Ihciughifiil replies as well. I really need to get 
away from the computer a bit, maybe walk the dog* 

System Requirements and Purcbasinc; Ineormahon 

Mailsinilh 2*1 requires Mac OS X version 10.1*5 or higlier; 
OS X version 10*2*6 or later is strongly recommended, 
(Integration with the OS X Address BcK)k requires 10.2 or later.) 
You can read more about Mailsuiitli's features and download a 
fully-functioning thiity-day demo from Bare Bones’s web site: 

http://www,barebone5*com/products/mai[smith/index*shtnil 

Mailsmith 2,1 costs $79 if purchased as a new product 
directly from Bare Bones. Upgrade and crexss-grade pricing is 
also available. 

SpamSieve is shipped with Mailsmith but separately 
lic ensed* You can more information here: 

http://wvvvv*c-command.com/spamsteve/ 

The latest version of SpamSieve as of this writing was 2.L1* 
References 

In 2(X)2, I wrote three articles on Mailsmith for TidBits, a 
review of Mailsmith 1*5 (http://www, tidbits*com/th-issues/TidBITS- 
638.html), and a pair of arlicles on distributed filtering 
(http://db,ti(ibits,com/getbits*acgi?tbser=1227). I say a lot in those 
earlier aiticles that is still pertinent to Mailsmith, and which 1 
didn’t wanr to repeal here, 1 recommend ihe earlier review in 
particular The articles on distributed filtering later 
metamorphosed into chapter 9 of the Mailsmith 2.0 user manual. 

Bare B<aTe,s has a web page intended to list AppleScript 
scripts for use with MailsiTiitli, here: 

http://wvvw,barebones.com/support/mailsmith/saiptjibrary.shtml 

As of this writing, only two scripts are listed* Many more scripts 
can Ix^ found here: 

http://www*mailsmith*org/scnpts/ 

The MaiLsmiih Talk li,st, .sponsored t)y Bare Bones, is hrequeiited 
hy Apj>leScript mavens, and they're generous in sharing their 
knowledge, 'llie threading script used as an example above was 
adapted from scripLs sliarcd on llic Mailsmith Talk list. 

Malt Neulx^rg's new book is AppleScript 7he Deftnidve 
Gtdde (O’Reilly, 2004), Miitt hit a homenin with his earlier book 
on RealBasic; he's hit another home run wiih ilii.s one. As it 
liappeiis, Matt reviewed Mailsmith 2*0 for TidBits 
Chttp://db.tlclbits*com/getblTs.acgi7tbart=r07289). I recommend hb 
review, which takes a cjuite different tack from this one. It i*s 
entitled, True Confessions of a Mailsmith Switelier*" 
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UNTAMCLIMC 
THE WEB 


By Kevin Hemenway, Imilaling Compimlor 

Programming and MySQL 


Modifying our MySQL database with the 
shell and PHP. 


Wl- fitiiilly added informaiion inu) our MySQL daiaba.se 
last issue, but tn a rather infantile way: by writing all the SQL 
statements (like those seen in Listing 1) into a text file and 
tiien passing them to MySQL with a command line, mysql 
mactech < mactech-insert.sql, which completes silently when 
successful. This is certainly helpful if we’re passing default 
information to be initialised in newly created databases, but 
not very useful if we want to programmatically access the 
information within. 

Listing 1: Three new SQL INSERT statements for oiir 

datab^._ 

mactcch-inscri .sql 

IHSERT INTO books 

SKT publicaiion = ”2000 DO OO”. 

title = '‘Object Griented Perl": 

INSERT INTO books 

SET publication “ ‘‘1959-00-00“, 
title = “MyEssQueEir': 

INSERT INTO books 

SET publicatloTi = “Z003 ■ 00- 00“, 

title = “PUP and MySQL Web Development": 

In this article, well talk about two more ways to manipulate 
data; through tlic MySQL interactive shelf and via PHP’s buili in 
database functions. First up, let’s walkthrough the interactive 
shelf which is quite helpful for quickly testing out new' SQL 
statements or applying immediate fixes wiihout new code 
overhead and development. 

The MySQL 1niera<tive Sheil 

Starting up the MySQL interactive .shell is mindlessly simple. 
Just type mysql and you 11 loe shown a mysqb prompt, similar to 
the ,shell prompt you see when you firsi enter the Terminal. 


Since we've yet to specify a database, we’re in a son of limlx): 
MySQL knrjws we're here, but weVe yet to tell it anything of 
iin[X)rt. First well show which databases have been configured, 
choose which one we'd like to work with, and then ask for a 
table listing: 

> iiiyaql 

Welcome lo the MySQL motilter. CoinJiiauds end with : or \g. 

Your MySQL connection id is 2 to server version: 4.0,13 

Type ‘help:* or ■\h' for help. 

Type '\c‘ to clear the buffer, 

mynql> SHOW DATABASES; 

4--P 

Database | 

-f- 

mactech 

mysql 

teat 

-1 

3 rowi 3 in set (0,7.6 sec) 
tiiysql) USE mac lech: 

Reading table information for completion of 
table and column names. You can turn off this 
feature to get a quicker startup with -A, 

Database changed 
DtysqP SHOW TABLES j 
+-+ 

Tables„ln„raactecb I 

4 - 

books I 

person | 

relationships [ 

- ■- 

3 rows in set (0.05 see) 

The mast ol^vious fact from the alx)vc is that all SQL 
commands must end with a semi-colon. If you happen to forget 
that termination, MySQL will change its shell prompt to show 
you it's waiting patiently fora complete command. Tlic following 
is the same command as l^efore, only split with new lines. Notice 
the prompt indicating an incomplete statement: 

mysql) SHOW 

> TABLES 

> : 


Kevin Hemenway, coautiior of Mac OS X Hacks and Spidering flacks, i.s lietter known m Mf>rhn.s TIT, the iTeator uf disobey.tom, whicli billfi itself 
“content for the clisi:ontented," Publisher anti developer of more home ctxjking tlian you could ever inuigine (like ilie popular opemstjurced aggregator 
AmphciaDesk, the best-kept gaming secret Gamegrene.com, the ever ignorable Nonsense Network, etc,), he’d rather lie nursing his wounds with a swift 
kick to the head. Contact him at morbus^drsobey.com. 
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A gcxKl portion of reiiders will know ihAi the shell opened 
by the Tennin^il gives you eoinni:ind line liistory (pres.s tlie IJl^ 
iirrow to see coinniands you’ve previously xyped) as well as file 
or directory completion (press 1AB after typing the first few 
letters). MySQL also supports tlicse lime-savers: pressing UP will 
show you SQLs you’ve typed previously, and pressing TAB 
when typing a table or c:olumn name will auto-cx>mplete the 
nearest match. 

In our previous work with SQL, w^eVe touched on the 
INSERT, UPDATE, and DELETE commands, WeVe yet to 
touch on the most often used, however, which is SELECT. 
While our previous statements have focused on adding, 
modifying, or deleting data, the sole purpose of SELECT is 
for displaying: 


mysql) SELECT * FROM books; 


t—^— 
id 1 
+ 

-H- 

title 

.j. 

-1" 

1 pubHcatiori 

1 

Spidering^ Hacks 

1 2003 11 01 1 

2 

Mac OS X Hacks 

1 2003-04-01 

3 

Object Otiented Perl 

1 2000-00-00 1 

4 

MyEssQaeEll 

1 1999-00-00 

5 

PHP and MySQL Web Development 

1 2003-00-00 1 


-4- 

-1- 


5 rows in set (0.00 sec) 

irysql) SELECT title, name FROM person: 

—- - +.- + 

I title I name | 

T-1-+ 

I Mr . I Kevin Heinenway | 

+-+-^ 

I trow in set (0,00 sec) 

niysql> SELECT * FROM relationnhlps WHERE book_ld = * 2 *: 

+ - + - + 

I peraon_id | book^id | 

+ — -+--+ 


1 row in set (0.05 sec) 

1he above show,s three different variants of a SELECT 
siaterncni—many more are possilile. The first is the easiest tf) 
understand: ‘"select everything from tlie lx)oks table”, llie 
second is an example of specifying only the columns you want 
to see, in any order. Even iliough title came alter name in our 
original CREATE siatement (last issue), SELECT allows us to 
reorder things however we decide Ixfst, The third statement is 
an example of mt>re intimately specifying which exact rows 
you'd like to retrieve. 

Comparing the above walkthrough to the command line 
we entered last issue (mysql mactech < mactech-insert.sql) 
gives us a betlcr undersUinding of what's going on. We 
specify the database to connect to (mactech; similar to USE 
mactech in the MySQL shell), and then send a bunch of SQL 
commands in a batch, as oppo.sed to manually entering them 
one at a rime. It doesn't take a giant leap of failli to realize 
that we can save the USE database step by specifying it on 
the command line: 


” > mysql mactech 

Reading table information for completion of 
table and oolumn namef:. You can turn off thin 
feature to get a quicker startup with -A. 

Welcome to the MySQL monitor. Commands end with ; or \g. 
Your HySQL conaectiem id is 2 to server version: 4.0,15 

Type 'help;* or '\h' for help. 

Type '\cl' to clear the buffer, 

mysql > [JPdAtK books SRT title = MySQL” 

> where title = ”MyEasQueEll”; 

Query OK, 1 row affected (0.02 sec) 

Rows matched; 1 Changed: 1 Warnings: 0 


n(yeql> SeLeCT id, title FRoM 

-> books WHERE title LIKE ‘iiSQL%^ 


-f— 

id 

1 title 


4 

5 

.x^ 

MySQL 

PllF and HySQL Web Developtnent 

2 rows in set (0.30 sec) 


The previous lisling show,s an example of entering the 
MySQL internctive shell with a database already selected, 
updating a row' of misspelling in our previous INSERT 
(LLstiiig 1), and then gelling a paUern maicfi with LIKE, The 
% cliaracters are bt)undaiy placeholders for “anytliing or 
nothing^ ,so our final statement finds the letters ^SQi” in the 
beginning, middle, or end of a title. Changing "SQL” lo **Tny” 
would return the same set of results, confirming that LIKE 
searches are case-insensitive. 

Up until now, all our SQI, commands have used capital 
letters, but you'II notice that they too are case-insensitive. 
For clarity, 1 prefer uppercase !>QL: it just makCsS things 
easier to mentally and visually parse after long hours of 
fevered coding. 

AccFJisiNG MySQL From PHP 
Our next step is to access our mactech database 
programmatically will) PUR You1l notice some similarities 
with the alinve imeraciive shell process: w'e connect to 
MySQL, choose a database, and issue some SQL queries. 
You 11 note that weVe passing the MySQL username and 
password we created with mysqLsetpermission a few 
columns back. This is iniptmant for security: just like you 
don't want your sister messing with your per.sonal files, you 
don't warn to make it loo easy for web interIoper.s to affect 
the various databases you maintain. In mosl cases, once 
you're finished developing an application, you’d tighten the 
user’s permission even further (say, to restrict DELETE and 
DROP access). 

Save the contents of Listing 2 into 
/Library/WebServer/Documents: 

Listing 2: PHP code for accessing our MySQL database. 

db_acce.s.s.phjT 

<hl>MySqL Database Accesii in PlLl</hl> 
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<?php 

$dbh “ mysq i_connect {“ localhost" »“ favf^iia rksman” ♦"***"} 
or die (^There was an errf>r fonncctiog to MySQL."): 

?> 


Before we delve deeper into our code, I wanted to show 
yon a one-c‘har‘acter-dinei-ence dial cun be used to improve 
security. Astute readers will notice that even lliough 1 meant 
davemarksman (du.* MySQl user created a few issues agti) I 
mistyped as favemarksman: 


■*m \ 






MySQL Database Access in PHP 


WamiflRi iny!iqt_ctimiecKi; Acc«ii dcawd fur Uiiscr 'f^VffRiaitsman^ki^ 
fiaAsii'Oiiii' YES) to /LlbnryAV«bScnw/l>aciiBaili^ tm line JJ 

Thwe wsji Oft emw to MySQL 




RRI);y/1Z7.0.P.ly<lb.«C*M.plM> ' 


tf li l/db^CHi.pbp 

i Database Access with PHP 

An ennr bw occDicd. Please ivpnn Ihi^ 


figure 2: No more infurmulion dmlamre. Much hetter 


With that out of llie way» we can now accomplish 
something, listing 4 contains complete (liut simple) PHl^ code 
to iasc^ri s()me information into the mactech database, view it, 
and then DELETE a biL As wiLli most piTognimming, there are 
many ways this c’an be done: moa* infomiation aixmt the 
different mysqL functions we've nf>! shown can be found at the 
PI IF web site: http://wvvw.php.net/manual/er\/rGfmysqLphp. 


Figure 1: An error iKcurred during the tiutabme connection, 

Here's the problem: if someone comes to our site and 
triggers this enor message, we’ve freely given them four pieces 
of valuable information that c'an be used against us for exploitive 
purposes, Wt?Ve told them we’re using MySQL as a database, 
that it’s installed on the same machine as the web server, that 
there's (po.ssibly) a user named favemarksman (a similar error 
wouki cxrcur if the username was correct, but nof die pa.ssword), 
and revealed a director>^ path (which, in this t'ase, infWs we're 
using OS X, a fifth fact). 

Listing 3 contains a much stronger version of our cixle, 
which removes any mention of the technology ix?ing used, and 
stops MySQL from spitting useful information to our visitors. Ihe 
rcjil magic happens with the @ symlx)l Ix^forc our function 
name: using it will silente any automatically visible errors. Tills 
makes for more secure code, as well as a more professiorail web 
site (i.e,, w'hai impression does it leave visitoi^s if they see 
nothing but errors?) 

Listing 3: Revised PIIP code for accessing our MySQI. 
database. 

db_acct:^.php, revised 

CbODataba^jo Aeceija in PHP</hl> 

<?plip 

$dbb = Gmy^ctl_comnect t“localh«jiit‘'."favcmarkiiBUiri" ,■"*** "I 
or die (“An error haf! occurred. Please report tbls.“); 
f> 


Tile revised output is shown in Figure 2: 


Listing 4: Finished PHP code for accessing our MySQL 
database, 

dh^arrt-ss.pljp, Gjiishrd 


ChDDatabaae Access In PTfP</hl)^ 

<7php 

// ttmneo 10 ihc daobiLse semn 

$dbh ™ @mysql_connect {“localhonT" *“dfivni[rtarksmaTi“ ^“* *^’*} 
or die (“ERROR: Could not connect to the datubaiijjP): 


// dimwic OUT database, 

0inysql_selecT_dl>( “muctedr ) 

Of die ("ERitOK: Could not soloct our database^*); 


// citatc a SQLMaicrocm. Notice tJiat tUroiifdt 
// PHRthc SQL lemiinailtts; scijikokm b optlojial. 

Sstatement ^ “INSERT INT€ person SKT 

name “ *Dav<? Hatk\ 

date_of_blrlh = '1901 03 3l\ 
title " *ifitern'. 

dosignatiem ^ "Builseye Hole Filler'": 

// sTamlani way- of cxcaiting SQL ihrougli PUP 
$responj;e = @raysql_query ( Sstateraent. $dbh ) ; 


// itiysqJ cnorO would yivt; tm much information for 
// a production site, hut this Is just an exampk' 
if {1 $reRponf:e) 1 print mysql^error () h ‘'\n’’: I 

// create and extxtiic anorher SQL stafcnicnt, 

$Sg_made_quL_o£ = "SELECT ‘ FROM person:'': 

$tespunEe = @myEql_query( $sg,.aade out of. $dbh ): 

// tills b one of a few ways to iterate through mws- 
pclnt ■'<ha>People. List #l</h3>": 

while ( Spernon = ^ysql_reich_a!:ray{ $reEponse ) ) I 


// column name Is array key 

priiiL "$persDiilid|. $personltitlel. 

Spersonfnamel. Sperson [designation]<br />": 


I 


// one more SQL statement, this time a deHe. 

$freedoin - “DELETE FROM person WHERE ntuae LIKE *%Mar%'": 
$responfle = ^ysql_query( Sfreedoin. 5dbli ): 
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// and nijikc sure he's really gpre. 

$Sg_tiiade_out_of *= “SELECT ‘ FROM porson;*'; 

Sresponse “ §Biy&tjl_qtieryt $sg_Tnade_out_'Pf. Sdbh 

// another way of heratmi; thrmi|dJ raws, only 
// 3s variables, not hash keys. Could gel messy, 
print ‘•<h3>People* List i!f2</h3>’': 

while ( $person " ftnysql^fetch, array ( Sresponse ) ) I 
extract ( Sperson ): // make colmwiff variables, 
print "$id* Stitle ^narae, $designatlen<br />": 


?> 


‘I'he resulis of running lliis script are in Figure 3. Since 
we're inserting a new record, then deleting it, successive loatis 
will assign the new record an ever-increasing seciuenliai ID, 
even though the data we're entering is exactly the same. 



Database Access in PHP 


People. Ltel ft 

1 . Mr.. Kevin Hemenway. 

30. liHcns. Daw Mxk. Bulheyi: Htik Fillc# 

People, LtsI II 

3, Mr. Kevin Hemenway, 




figure 3: The final resulLs of Qur database access in Pfll{ 


IIOMI^ORK MAUGNMENTS 


A,s is typical in a four-page article, weVe barely touched the 
surface of what PUP ran do in regards u> dauiba,se access and 
handling* Next mtrnih, well change gears and see how Perl 
handlers ilie .same logic. Until then, contact the teacher at 
morbusOdisobeyxom. 

• For more inft>nmtion aixjut secure oxling witit PHP, check out 

the following articles: *'A Study In Scarlet: Exploiting Conrunon 
Vulnerabilities in l^HP Applications" from Shaun Clowes 
(http://www.securereality.com.au/studylnscarlel.txt), and ''"len Security 
Checks for PHP'’ from Clanc 7 Malcolm (Part 1: 

http://www.onlamp.eom/pub/a/php/2003/03/20/php_seajrity, html and 
Pan 2: http://www.onlamp.corrVpub/a/php/2003/04/03/php_security.html). 

■ Since you'll l>e ai 0'Reilly'.s OnlAM? site anyways, check out 
the rest of the PHP DevOnter at http://www.on la mp.COnVphp/. 
The “PHP Foundations'^ (http://Www.oreillyneLcom/pub/au/135) 
series has a three-part article on “PHP Security", as well as 
recent crash courses for MySQL (which, in hirid.sight, uses the 
same clidied '‘(>erson/l>ook" example I did* Rxcelsior!) 

• For more on die @ error silencer, see 

http://us3.php.net/operalors.errorcontrol. 
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STARTING A 
BUSINESS 


By Chris Kilhourn 

Business Planning 


My first business plan was laughable. 


There were ridiculous assumpiions, glaring omissions and 
there were more marketing fluff words in it llian actual 
substance. Hven though E cringe when I read it today, it still put 
me significantly ahead of die game wlien talking to bankers, 
[X>tential investors, and clients. Why? Because 1 aciually had a 
plan to show them, flaws and all. 

like a college degree, a business plan neither 
guarantees future success, nor proves that you have 
mastered a given subject, but it does show^ that you [hil in 
the time to think about your business, and how it will 
operate. The time spent writing your plan will force you to 
think about, and explore all the facets of your business. It 
will help you to uncover hidden assumptions, crystallize 
how you will actually make money, and assist you in 
developing reaiisitc goals for your business, 

1 am still amazed at the number of entrepreneurs I meet 
who feel that writing a business plan is not a good use of 
their time. Tlicir excuses range the gamut from claiming to 
not have enough lime to write it to blithely claiming that 
tiiey do not need one because die business is doing well 
without one. 

If you ever expect to open a line of credit with a bank or 
vendor, raise money fre^m private individuals or venture 
capitalists, or recruit senior management for your company, you 
will need a business plan. Without a business plan, you simply 
will not l>e taken seriously by liiase people, and you will be 
wasting everyone’s time, including your own. 

What Sholtld Bl In Your Business Pi^n 

A business plan should answer what I like to call the 
Golden Quad; 

• Wliat Will the business do? 

• Where will your cusLomerx c:ome from, and how will you sell 
to them? 


• How will tire company make money? 

• Who will run die business, and why aie they qualified to do so? 

I call them llie Golden Quad l>ecause without answering them 
in your plan, you will likely never .strike gold in your business. 

As you work through writing your plan, continually ask 
yourself if you are answering these four questions clearly, and 
directly. For every sentence that is in the plan, if it docs not 
speak to or support the Golden Quad, do not include it, 

I have read plans with insightful analysis of markets, and 
wonderful descriptions of cutting-edge technology^ and that 
were very well-written, but didnl tell me a damn thing about the 
company’s pr{Kluct or service, who llieir customers were, how 
they were going to make money, and why the managers were 
qualified to lead the company. In shon, they were a great read, 
but useless as plans. 

I would lx: remises unless 1 emphasized the iinponanc:e of 
the financial component of the business plan. Your plan should 
include projected cash flow and income fproflt and loss,) 
statements, a Iralance sheet, a listing of all capital (expensive) 
equipment, and a list of the assumptions that went into tlte 
pro jetted financial data. 

To a person, the bankers and investors I have met looked 
at my financial data before reading the plan, or executive 
summary. If your financial numt>ers do not add up, are 
unclear, or your assumptions are incorrect, your plan will not 
l^e read. Period. 

The gtKxi news is that there are many free tot)ls for business 
financial planning available. Ihe Small Business Administration 
provides a wealth of information in this area on their web site, 
for example. If numbers are not your strong suit, you will want 
to hire or cxintract for some help in this area. 

Who Are You Wriong The Pusn Ft)R? 

Your business plan is being written for a variety of 
audiences. First and foremtJst, you write it for yourself. You 
may have spent months or even years thinking about starting 
your busines.s, but Fd be willing to bet you spent most of 


C:hris Kilboum Ls an independent small business, network and web infra.slrueture consultant, Chris is also ihe founder of digitaLforcst, Inc., 
http://www.forest.net which offers database, application and web hosting services in addition to server colocation. When he's not out running marathons, 
you may contact him at chrisk@fQfest.n>er. 
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thill time thinking about what you were going to do, not 
how much floor space, and equipment each employee 
would require. 

Your business plan will become your guide, your to-do 
list, and your touchstone witen you lose your way. With the 
myriad details that must be attended to in any business, re¬ 
reading my business plan on a pertcKiit^ l>asis became a ritual 
for me. It was the compass tliat let me know if i was still 
heading in die right direction. 

Secondly, you write your business plan for your 
employees. Post dot-com crasli, savvy interviewees asked to 
see our business plan, which we gladly furnished io lliem, 
sans financial infonnation. A clearly wrilien, and shared 
business plan shows potential, and existing employees that 
managemenl has thought through the business, and is willing 
to be held accountable to it. 

By sharing your plan with your employees, you invest 
them in the vision of where the business is going. If you hide 
it fr{>m them, which seems to be an unfortunate practice at 
far loo many businesses, management directives lend to be 
questioned more vigorously. Think about it: if you were 
fallowing someone into unknown lerritory, would you be 
more or less inclined to t|yeslion their judgment and 
authority if they shared with you up front where they were 
planning to go? As an adiled bonus, you gain the benefit of 
employee input into the plan. 

You write your business plan For your hankers and vendors. 
Bankers and vendors who extend credit must perform a risk 
asse,ssrnent before deciding to grant you credit. Providing them 
your business plan with a sound rinancia! intxlel in it helps them 
to understand the financial risk they will be taking with you. 
Fn)ni ixrrsonal experience I can tell you that no plan, or one that 
has unclear financial information in it, will prevent you from 
receiving credit which can significantly inhibit the growdi of 
your business. 

Finally, you write your plan for your investors. Llnless you 
are a seasoned eniretxeneur with several business successes 
under your belt, the only people you will Ise able to raise money 
from without a plan will be your friends and family. The 
business plan also he I [is you cieate your ‘elevator pitch.' This is 
a 3- to 5-ininute verbal pitch that an.swer.s ilic Golden Quad, 
and hopefully hDok.s a poieniial investor to learn more about 
your company. 

We will cover fundraising in a future column, but a truism 
in fundraising is that people invest in jxople not plans, hut 
without a plan, an investor will not invest with a person. Period. 
No plan = no investment money. 

How LoNti Should Tul Pun Be? 

You should create three versions of your business plan, and 
L*ac[i version will vary in length, and content dcqjending upon 
whom the target audient'e is. 


The first version you create should be a detailed full 
plan that should be a.s long as it needs to be to aUsSwer the 
Golden Quad, but keep it under 20 pages with supporting 
materials. Any thing longer than that and you risk reader 
fatigue. If you feel that including a large amount of 
supporting material is necessary, consider creating a separate 
document that includes them. Bear in mind that unless you 
are submitting your plan to a venture capital firm, large 
amounts of supplemental, and supporting information are 
routinely ignored. 

Tills detailed plan is for you, for your employees, for 
investors who expres^s .serious interest in investing and for 
bankers or vendors extending you signific’ant credit, 

Tlie second version should be an executive summary no 
more than 4 pages in lengtli, not counting supporting financial 
documents. Tliis sliould l>e a succinct, Ixiiletl-down version of 
your full plan tliat provides enough infonnalion to dearly 
answer the Golden Quad. 

llie executive summary plan is an overview version for 
potential investors, ptXential employee.s and vendors who you 
plan to work with on a regular basis Ixit for whom the full plan 
would lie overkill. 

The tliird version sliould lie a bullet-pointed slide version of 
the executive summary. For ihis third version, select the talking 
points of I he executive siunmary and then develop a narrative to 
c'over each yxjint. 

Tins slide version is great lor sales presentations, and 
investor [pitches. *Tlie Ilexibility of doing it as digital content is 
that you can tailor your message to each group or individual you 
presemt it to. 

Shaking Your Plan 

As described earlier, you should Ive sharing your business 
plan witii a variety of people. When it comes to sharing it, 
exercase some common sense when doing so. 

This means that you should have versions that include 
and omit financial data, proprietary information and 
competitive analyses. You should also include a version and 
tracking number on each copy that you distribute and then 
keep a list of who received which. Each page should be 
marked, ‘"Copyrigln [Firm Name.] Proprietary and 
Confidential - Do Not Djsiribiiie," and include the tracking 
and version nunilier 

Many entrepreneurs are reluctant to share their plan.s out of 
a fear that tlieir infortmition could end up in a eom|>etitor's 
hands. In genenil, this is an overblown fear Unless you are the 
target of difetied corporate espionage, most people will Dip 
through your [ilan, and then shove it in a drawer, never to lx* 
seen again. 

For anyone who is not a potential investor however, you 
should protect your rights by having them sign a non¬ 
disclosure agreement prior to giving them a plan. In the 
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event that you discover that the mforniation lias been shared 
willi parties that should not [>e privy to your plan, the 
tracking number of the plan then provides you with strong 
legal recourse to sue for damages. Consult a lawyer for the 
finer points of this issue. There have been cases where 
disclosure of business-plan data restihed in financial 
settlements that made pursying the business idea not worth 
tile financial risk! 

When it comes to investors you just have to go out on a 
limb and trust tliai they will not unduly share your plan. 1 will 
t:(>ver this process in more detail in a later column, but suffice to 
say that investors do share plans with others, but it is only in 
extremely rare eases tliat this l:>elx;tvioF will cause you material 
harm. In most cases, tliLs is a g(K)d thing. 

Ri^i-^VRCii mu Knowipdge - Yoirn Key to a SncjCE^FOi Ptm 

You will need to do research in order to write your 
business plan. The depth and tjualiiy of your researclj and 
how much you learn will be redected clearly in your plan. 
The more researcli that you perform^ the easier it will be to 
write your plan. 

I spent close to live months doing research before 
writing my first business plan. This time was spent reading 
alK)ut as many business failures and successes as 1 could 
find, perlbrmtng market research and financial planning 
massaging spreadsheets. 

Being fully in tlie camp that forewarned is forearmed, 1 
strongly encourage you study business failures, small and laigc. 
Santayana's warning, **Tliose who cannot rememlxfr the past are 
contiemned to repeat it/ comes strongly into filay here. 
Businesses tend to tail and succeed for very predictal^le, well- 
ckK’timentcd reastjns. You should learn what they are l^fore you 
ever take a dollar fmm a c-ustomer or write your plan. Knowing 
what Liie pitfalls and accelerators are will help guide you in 
crafting your plan. 

Questioas that you will simply have to answer in your 
research for your business plan are; How' large is your target 
market in ptncmial number of customers ami in dollar value? 
Where are these customers located and how will you be best 
be able to .sell to them? What e<tuipment will you need? How 
many employees will you need? Who is yf>ur competition? 
What are the barriers to entry' for competitors in your market? 
Is what you are doing novel and unique, or is it well-known? 
If it is wcll-knowm, how will you make money in an already 
established market? 

There are many other tiuestif>ns that will need to asked 
and answered, but they will vary by the industry you are 
competing in. If the thought of a research project terrifies you, 
and I’ve met more ilian a few people lor whom this is the case, 
there are a wide variety' of sources and support that can help 
you with tile proces.s. 


Tlie lx.‘.st, and in my opinion, first place to start when you 
liegin your business plan is your local Small Business 
Administration office or tJieir well site at httpi/Zwww.sba.gov. The 
SBA will lx: able to provide you with business plan samples, 
checklists, basic market research, networking, and their most 
valuable resource, SCORK counselors. 

Tile SCORE counselors are retired and working excx:utives, 
and each of Uiem have I'seen in your shixrs liefore in trying to 
pull a busine,ss plan together. Tliey will sit down witli you, and 
review your plan if you have one, or help guide you in 
com[>iling yt>ur own, SCORE counselors will provide you with 
one-on-one, individuali7.ed feedback while sharing their 
knowledge, and experience with you. You should avail yourself 
of dteir services. 

Another underuiili/ed avenue of research, and knowledge 
Ls your lot'aJ university's busine.ss school and associated library. 
There are legion.s of MBA students kx^king for real-world 
experience in business via internships, and special research 
projects. In many cases, these services can lx? had for little to no 
cost. Students get material for prtjjecLs, you get data for your 
plan, and everyone’s happy. Business schtK^I libraries also 
contain innumerable business case studies, books on l>usiness 
planning, and stories of business successes and failures. 
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NtiL Lc) l)e overlooked is the InLemet When I was pulling 
logclher my business plan in 1994, Inter net l)ysiness 
resources were few and far between. T<Klay, Uiere is a vast 
amount of information pttblished by the Si BA, business 
schools, and entrepreneurs, A quick spin through a search 
engine will present you with a wealth of useful, fand not so 
useful,) infijrmation. The caveat here is to second-sourc:e 
facLs and figures found on the Internet with known offline 
information sources. 

Format of rm Pb\N 

So how should your plan be formatted^ It should have the 
following sections: 

Business Description 

This is ilie 'nut’ of what your company does, and how^ you 
plan to make money at it, Tltis is your business plan 
introduction, and it is the liare^boiies description of why you are 
in business, and tlie geneml view of ilie financial opportunity 
that you are pursuing. 

Company Overview 

This is a more detailed Itxik at llie company. You should 
describe the company's l>usincss stntcUire, provide a general 
overview of current operations inchiding employee and 
customer counts, where you are kx:alcd, the current level of 
business development, (,seed, start-up, estal>iished firm, cic.J, 
and a brief history to date. 

Business Opportunity 

This part strikes right at the first question of the Golden 
Quad - whai will the business do? Here ytju should detail how 
large your potential market is in number of customers, and 
revenue. 'iTie best way to think about striiciuring this section 
is to explain what problem you are solving for your 
customers. Detail the problem, then explain how your 
company will solve that problem for them, and make juoney 
from providing the solution. 

Market Analysis 

Here is where most of the research you have done will 
sliine ilirough. Demonstrate that you know that your overall 
market is segmented, and detail wliich segment you will go 
after, and why you are going after them as opjxjsed to others. 
Descrilx* historical trends, and market blips, good and bad, and 
how you plan to ride them to success. 

Strategy^ 

Descrilx? and detail how' you will execute your sales and 
marketing strategy for the customers you identified in the 
Business Opportunity section, while lying it into the Market 
Analysis section. This is all alx)ut how you will attack your 
market, take it over, and make money. You will need to explain 


here the core finanr'ial model of the company. Is it direct sales? 
A software upgrade revenue model? A tnonlhly annuity for 
service's rendered? Lay it all out here. 

Cx>mpcl]tjon 

Every business has competition, whether they think they do 
or not. Convince your readers that you understand your 
competition, that you can penetrate their Irarriers to entry into 
their markets, and then eiea yt)ur own barriers to keep them out 
of yours. Your strategy should be clearly reflec!ted in how you 
manage your competition. 

Management Biographies 

These shtmld be single-paragraph resumes with an 
emphasis on career achievements that are applicable to the 
current business encleavi>r. Your goal here is to convince the 
reader that your team Itas the experienc*e, knowledge, and skills 
to execute the plan successfully. 

Siiinmaiy Financial Data and Projections 

Welcome to the land of spreadsheets and numbers. This 
.setlion should include a 3-year look at actual, and projected 
cush flow and prtifit and loss. Income and costs should be 
broadly grouped for the executive .summary version of your 
plan, and be detailed in the full [>lan. A balance sheet should 
also be included if there are already company assets. 

Additionally, a list of all the financial assumptions thai 
went into your projections must be included. Good 
examples of assumptions are rale.s of inflation, interest, and 
costs for things like equipment and employees. The more 
detailed your financial plans, the easier it will be for you, 
your hankers, and your investors to understand the core 
financial model of your company; and to adjust it as you 
move forward. 

As an example, digitalJorest's financial model is a 2MB, 
iO-tali spreadsheet where if you adju.sl the square footage 
for employee offices, ir will automatically update and adjust 
costs for office space and fixtures and update cash flow and 
income projections. There are similar ‘kmtl^s and sliders' for 
service costs and revenue that are linked back to the 
financial reports. 

Subscription Agreement 

This is a section ihai should only be distribuied with the 
full business plan, and included when you are fundraising. 
'I'he subscription agreement lays out the terms and 
conditions for investors, Tlie subscription agreement should 
Ix^ provided l>y yom legal team. Don't worry about this 
section right now unless you are actively soliciting large 
sums from investors. 

As a final word on form, ]>rini it on a laser printer, not 
an inkjet, have it bound with a clear plastic cover and have 
a cover page with your company name on it with your logo, 
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prL^ferably in color While the content is wliai really matters, 
your plan is more likely to be favorably received if its 
prescniaiion kniks professional. 

Reauty Chrck 

.Siirpn.sin^ly, one of the most useful things abf>ut a business 
plan tliat is rarely mentioned Is the reality che< k it provides for 
your business. Working thrftugh the financial, and operaiiftnal 
assumptions for the business in your plan will liigliJiglu 
absurdities, and processes that just won't work. 

I still clearly recall a digital.forest planning meeting to 
review our financial model, and ending up with a $3 billkm a 
yeiir revenue stream after four years of optTaiions. 'lliose of us 
in the rcxim hatl a g<K)d chuckle amund the table as we knew 
that was a aanpletely ridiculous numlx^r, It highlighted lliat 
there must be a liidden assumption somewhere in the plan that 
was grossly inflating revenue. 

The source identified and fixed, we came back down to 
li;inli witli a projected $300 million a yc^ar company after four 
years of 0|:>eration, (Hey, it was IfW; everyone was thinking that 
way!) Which only goes to sliow that even when you think 
you've figured everything out, and triple-checked your 
a.ssumptions, you can still be wildly wrong. 

ft is important to question every result and goal tn your 
plan, even if they seem so rock-solid tlial it feels like a waste of 
time. At every major iteration of the digitaliorest business plan, 
we have lieen able to pnme out tacit assuiiifMiQns that were 
bassed on wishful thinking, not on reality. If you don't do it first 
in the privac 7 of your office, it is likely tliat your Ixinkers and 
investors will do so in a pubitc space in front of people that you 
are trying to impress. 

lATHKK, ReNSI:, REPEAT 

lJu,siness<ts that have business plans that are not updated on 
a regular basis tend be more at risk of lailure ihan businesses 
without a plan at all. Why? Ite'aiLse a business plan tliat i.s not 
u|Klaled can act as a dead hand, guiding the company towards 
its doom. 

Tlie Soviets were fantastic' planners. They generated 5-yeiir 
plan afu;r 5-year plan for things like farm collectivization, and 
industrial output targets. What they were Sfx:ctac ularly crappy at 
was upckiting their plans. Their plans would say they were going 
to make 75,000 shoes even if all ilie cows died, and there was 
no leather with whic'h to make tlie shoes. 

Far too many business people an like Soviets, and feel that 
once their business plan is written, they're done. 

Nothing could he further from the truth. Competitors 
come and go, technology shifts, inflation goes up or down, 
things go w^ell, things go poorly. Each of these, and a myriad 
of others not listed, are excellcai reasons ro update your 
business plan. 

Without periodically updating yt>ur business plan, you run 
the risk of delivering products, and services your clients do not 


want or operating your bu.siness at a loss because market sliiAs 
have changed the profit mrxlel for your company, 

Andy Grove of Intel says that only the fxtranoid survive. The 
reason for tliat is because the paranoid are constantly re¬ 
evaluating the status (fuo, and adjusting their plans accordingly 
as they go along. 

The Lis^r Laugh 

While I still cringe when I re-read my first busine.ss plan, 
over the years it has evolved into a powerful document llial Ikls 
evolved wiih the times. It has providetl direciion and puqx>se to 
employees, investors judged the merits of it l>y enmisting their 
funds to digital.forest iKvausi.^ of it, and companies wc have 
acquired fell safe that we would treat their customers, and their 
staff well because wc clearly knew^ what wc were doing - it was 
written down for all to see. 

NETF MONTTl: Accountants, lawyers and bankers - fun 
people to s[>end time with; really! 

IDo you Ixive a business (juestion that you would like 
Linswercd? Send it along to chrisk@forest.net 
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ECLIPSE IDE 


By Kuheri Kleiman 

The Cool Side of the Moon 


The Eclipse IDE on the Macintosh 


The EciiPSE IDE 

In this Jiftide we'll lour ihe Eclipse IDF jintl discuss how k 
fits Into the Macintosh architecture, tbcaising on development for 
java. We will go lieyond hype and precisely look at how Eclipse 
now stands on the Maeinlosli. 

Why E(xipse? 

With so many excellent, even free, IDEs oul iherc, why 
Eclipse? For the writer, there are three reasons. First, Eclipse is 
intuitive to team and use, ami fusi one IDE serves a wide variety 
of purposes—from java, AGP, web, to C/C++ development. The 
investment pays gtxjd dividends. 

Second, Eclipse's general architecture has created a 
global community of plug-in develo|X!rs from whom 1 draw 
a wide variety of ukjIs. Some research groups release plug¬ 
ins unavailable elsewhere. In a pinch, I can easily roll my 
own. One way to think of Eclipse is as Bmiics for the User 
Interface genenition. While Lisp is the language for extending 
Emacs, for Eclipse Uic language is the plug-in architecture 
and Java, 

Finally, Tm addicted to Eclipse's extensive and reliable 
refactoring features: ihe^y liave saved my overnighters for more 
useful work than code wrestling. 

Features and Benefits 

Eclipse is a robust, open-source IDE based on a general 
plug-in architecture. All components of Eclipse are plug-ins. The 
most widely used plug-in is j£wa IMMdopmem Tooikll GDI')- 
Another is the new' C/C++ Dcwhpmeul Toolkit (CDT), 
supjx^rling the GNU gcc compilers, iitcKiding Objective C. The 
Eclipse IDE runs on and has cross-platform development 
libraries for MacOS-Carbon, Win32-Win32, Win32-CE/win32, 
Solaris/inotif, QNX/photon, Linux/tfi, Linux/motif, Linux/gik, 
HPUX^^motif, and AlX/moiif. 

Apart from tlic Java and C++ editors, lliere are plug-in 
editors for UML, XMI i<oXyg(ni/>), Ant, vistjul programming, 


and more. Editors can l>e extended and share their resources 
with other plug-ins. One need not re-invent the wheel to add a 
small but useful ctmtribution. To write your own editor, use the 
Craphical Editor Frametwrk (GEE) plug-in. 

There are plug-ins ft>r team sup[X>it (CVS sync hronization, 
including SSH2 in Eclipse 30), JUnit, code insirumentation 
(C7o£jfT), Aulornated Stiftware Quality (HymlesX web applinttion 
server build and deployment (e.g., {or JBoss, A}Micbe Tomcat, 
IBM Websphere, BFA Wehhgic), a platform delivery franiew'ork 
{OSGiX and more. There is an Eclipse prt^ject developing end-to- 
end web service development plug-ins. 

Naturally, there is a Pltigdn i)ei>t^lopnient Fjwiwnmmt 
tPDE), itself a plug-in, for creating plug-ins. And, for theJDT and 
the Fdip.se IDE, the help system has a w'el I-documented Jam 
DeiH/iopnieni Enmronmenl Pittg-in Demhjm' Guide and a 
Piatfonn Piugdn Dein/hpcr Guide, res(X"nively. 

Eclipse on the Macintosh 

So how is Ft'lipse integrated with the Mac? Eclipse uses 
the Carbon library via its Standard Wkfgei Toolkit (SWT). 
While Swing generally implements its widgets with a 
combination of Java and native code, SWT mapx its widgets to 
CarlKui widgets via one-K>one C calls to the native widget 
APIs. When debugging, this means that when you run into a 
handle lo a Carbon widget, you see precisely whai you w'oukl 
ex peel if you were wcjrking in Ohjeciive C. By default, Eclipse 
ohiains the Aqua look-and-feel and the best performance that 
Carlion can afford. 

SWT emulates non-native w'idgets, and there is a sepanite 
SWT library for each plaiforiTi. In addiliuri, there’s a shared 
lilxary that glue.s SWT Java calls to the native APL At the lowe.st 
level, SWV maps lo the CarhKm Event Manager I listing 1). 

Listing 1: SWT Event lxK>p Life Cycle 

Event kH)p Ufiiiif! ^ window. Display interacis with lire (iarism event managcT to liandJc 
the applkmion event kwip vU rcadAmlrtL'ipatt hO-A SheJl is a >vinilow vfilirely handled 
I>y live l.aiix>n Windtm Manajjer: ii is insLiiiiriateil with the Display as. its parent. 

Display display Display (J: 


Ruben Kleinian is a software archiicci anti wriler now devdoping an inldligent iK-rsonal assistant, Fonnerly, he was Principal Scientist at Apple 
Ctimputer, Inc., Ardiilect at SGI, and MemlKT of 'I'ediJiitaJ Staff in Al at Corptrration and the Micmdettninics and Computer lechnology 
Coqxiration. Ite lias lectured tm aTtifinal intelligence and objettHrriented systems, holds various [laieiiLs, and has wriuen For tetdinrcal journals ami 
popular magazines. Ruben lives in Northern Qiltfomia and he may l>c reached at ruben@njbenkteifDan.eom. 
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SfiGll wlnJt)!# = nev Shell (display); 
wlndqw,open(): 

while (fvindw. isQlsposed ()) [ 
if (idisplay.readAiidDlspatch() ] 
display^sleepO ; 

I 

display.diflposeO ; 

This is the mam application thread. readAndDispatch() maps 
native events into SWT events. Carbon event loop timers are 
provided by Display ineihods. lasieners can lie registered on any 
event type. 

We can fork other threads for long-running tasks. Such 
threads can call back into I lie main thread, but only through 
an API that ensures that the interaction with the Ul is safe. This 
is provided by Display's synch Exec(Runnabie> and 
aSynchExec(Runnable) melliods; they allow the calling thread 
to block or not lilock, respectively, until the Runnable 
executes. For example, the forked thread may go off to zip 
some files for the user interface and, when done, use one of 
the *Exec(Runnable) rtiethods to display a message to the user. 
From there on, Fclipse's user interface is based on .SWT and 
JFace—a higher-level library pawklmg Modei-X^iew-Controiier- 
like access to SWT. 

What about Cocoa? Cocoa and SWT are ccunparahle 
frameworks, hut SWT is founded on Carbon. The decision to 
use Carixin is arguable, liut, since Carlxin includes more 
lower-level APIs, it can provide some nraneuvering rtiom for 
the SWT implementors than Cocoa. There has been some 
work in pre-release versions of P'cl ipse 3 0 to support 
Cadxin's Hi View, but a higher priority of Lite Hclipse team 
seems to be to achieve a faster and more robust MacOS 
implementation In the near term. This, as we shall see, 
should be a weicome move. 

How does Interface Builder fit in? Interlace Builder 
generates code stubs suitalile ff>r Apple's Java extensions, but 
it generates NS* classes, not SWT or Swing classes. Since 
Interface liuilder's output is a nih hie, we could write a nib file 
reader in javaCC and a generator for SW1' or Swing using 
Carlxm or Cocoa nibs. Alas, at the time of this WTiftng, no such 
feature exists. 

Finally: how usable is Eclipse on a Mac right now? The 
first version of Eclipse was released in Ntivember of 2001, but 
it wasn’t until March 2003 that Eclipse support lor the Mac 
started with Eclipse 2.T There is little to complain about the 
Aqua look-and-feel (Figure 1 ). However, though on a 
Titanium PowerBook G4, at 667Mnz and 512MB RAM, large 
project builds are as fast as one would expect, but tool ti[is 
and code assist are sluggish in Helip.se 2J.2, Eclipse 2J.2 is 
not up to par with its excellent performance e,g., 
Windows or Red Hat IJnux. Eclipse developers arc working 
to close this gap. 

iNSTAUJtVG ECUPSE 

Eclipse 2.1.X+ uses JRH so you need MacOS 10.2+. 
Eclipse requires 100 Mti on disk and 256 MB of system RAM. To 


install Eclipse, go to http://www.edipse.org and follow the 
download link to a MacOS version, with care to use Safari and 
die latest version of StiifflL, as instructed. We’ll use Eclipse 
version 2.L2 in this article. To uninstall Eclipse, just throw away 
the whole Folder. 

GeIIU^G OmiiJNTED 

Three lips. First, the help system is indispensable. M has 
clear, often illustrated, step-by-step, task-oriented instructions, 
tutorials, Al^Is, and overviews of [ilatform and plug-in features. 
The key areas you should peaise are the Jam Dcwhfmtml fiser 
Cuuie and the Workhcmch l/ser Cuide. Since almost all the 
information you’ll ever need is there, it will pay you to gel 
acquainted with these pages. 

Second, seleta the Help -> About Eclipse Platform menu for 
an overview of the Eclii^se features and pl ug-ins Installed in your 
system, An Eclipse feature is a group of related plug-ins. 

Finally, access your global preferences settings via the 
Window -> Preferences menu. Explore the Workbench and 
Java settings, especially those for the Java source editor’s 
code formatting and code assist, as well as the auto- 
generation tif comments and names for files, classes, 
methods, fields, etc. 

What’s Yoim Ptiiisr Of Vie«? 

A View is a panel inside the Eclipse workbench window. 
For example, the Java Development Toolkit (JDT) plug-in and iLs 
extensions provide the following views: 

• An editor view, lliere are editors supponing many file types 
(c.g., Java or AspectJ class, Ant build file, property file). 
Depending on your prLTcrence.s, you also have access to 
other editors (e.g., Emacs) by clicking on a file and using the 
Open With,,, context menu. (Eclipse 3^0 early-access has an 
Emacs key binding option.) 

• A view of the class inheritance tree (the Hierarchy View). Tn 
Eclipse 3^0 there is a Method Call view, 

• The system console (the Console View), 

• The “todos,“ error, build and other tool warnings, etc. (the 

Tasks View). 

• The hierarchical view (>f all of the resources in your project 
(the Package Explorer View). 

• An outline of a cla.ss’s memlx^rs and imparted classes (the 

Outline View). 

• Packages. Types and Members views that display and let you 
to fcxais on Java packages, classes, and memlxrns, respeaivcly. 

• The Synchronize view allows you to synchronize your 
project Willi a CVS repositoiy. 

■ Tf yoti use the Apache Ant too!, the Ant View allows you to 
look at your Ant xml file’s tasks in outline and run them 
individually, or to look at the prijpenies of your Ant file. 

• Hclipse^s Aspect] IDE plug-in enhances iriosi of the alxjvc 
vicw.s to support Aspect-Orienred Programming (AGP) using 
the Aspect! language. For example, the Outline view lets you 
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see whether a member is advised, and by whom and how it 
is inlercepled. 

Many more views are availaijie from free and coinmerciai 
plugins* Views ec)ljalx)rate through the plug-in architecture- For 
example, the Members view’s contents on whicli package is 
selected in the Packages view* Each view has a mini-toolbar, 
and sometimes drop-down and contextual nieniis, as well as 
L(H)1 icons* Try them out- Double-clicking on a view's mini- 
toolbar expands/minimizes the view* 

Although you can open any of these views via the Window 
-> Show View menu, you will typically work with a group of 
views: this is where perspectives come in* 

It Depends On Your PF*iisPEc;nvE 
A perspective is jtist a grrjup and placement of views in a 
window t Figure 1). The Edif^ejam Development Toolkit plug¬ 
in comes with some ready-made perspectives. You can cieale 
your custom perspectives based on existing perspectives by 
combining and arranging the views you want. 



figure i. Default *"Java Fers{)ectiw'* 

JDTs most useful pcrsfiectives are the so-called Java, Java 
Browsing, and Debug perspectives. You can open tliem by 
selecting the Window-> Open Perspective menu. You create new 
perspectives by adding, deleting, and dragging views around an 
existing f>erspective. When you place more than one view on 
the same real estate, view selection tabs appear. Yi>u can open 
multiple perspectives on scpamte windows. 

Creating A Java Project 

Let's create a project. (If you want to learn more about what 
follows, review die help system's Java Development User Guide 
-> Getting Started -> Basic Tutorial section*) 


• Open the Eclipse IDE. 

• Go to File -> New -> Project,,, 'the projeci wizard’s dialog lets 
you select the type of project. Select Java Project and click 
Next. 

• Name die project EclipseApp and specify its location in disk 
(the default loanion is the workspace folder). Click Next. 

• ITtis Java Settings dialog allows you to specify die 
directories for the source and class files and liliraries* First, 
make sure that you are looking at tlie dialog’s Source tab. 
7'he default directory for sources should be EdipseApp/sre* 
If it is not, select the EclipseApp fokler icon, click 
Edit^.and then click on the Create New Folder,,.burton 
and name the folder sre* Ensure that EdIpseApp/build is the 
Default output folder at the dialog’s bottom. If it is not, 
type it in. 

• Click on the Libraries tab to set up our build padi* You 
sliould see your default JRE or JDK already in it* We won't 
need to add any libraries besides the JDK's, so click Finish. 

You should now see the EclipseApp projeci in tlie Package 
Explorer view of Eclipse. 

Working With Source Code 

In the Package Explorer select the sre hilder and select 
File -> New -> Package. In ilie dialog, name the package 
mypackage and dick Finish. Now select File -> New -> Class. 
Fill in the form to create a class named HairyCtass in 
mypackage. The class opens in the java editor. Notice that the 
snih for the constructor is marked with a // TODO task* The 
laiiLT appears in the Tasks view; double-dick on a task to go 
to its location. You can set task preferences in Windows -> 
Preferences -> Task Tags. 

For the final contents of this das*s, see Listing 2* Let's 
enter the public fieltl at the top. Just type pu and enter 
Command-Space. The code assist feature brings up the 
available completions in the context. You can navigate the 
completions menu with the arrow keys or mouse to view 
Java docs, if available, or keep typing to reduce the 
suggestions* I lit return to fire a highlighted completion. Type 
the rest of the line using autocompletion to get the hang of 
it. When you get to third field, type up to public Ve and use 
autocompletion to select Vector. Note that java.util.Vector is 
now in the imports list. Now delete this line, retype it 
without autocompletion, and save it. Saving a file recompiles 
the class. There should now^ be squiggly lines around the 
name Vector, When the mouse hovers over the .squiggles, the 
error message displays. There should be an error icon on the 
left margin of the line; depress the moase on it to gel 
suggestions for fixing the problem. Douhlc-dicking on any 
suggestion makes Eclipse implement it. As youVe been 
navigating the code, you’ve probably tried the Outline view, 
or perliaps you've switched to the java Browsing perspective 
or created your own. Finish up this class. 
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Now create a class called My Main in die same package and, 
in the New Java Class dialog check the Itox to create a 
main{String[] args} stub. Knter the code in listing 2. 

HairyClass is rather^ well,,, hairy? Select the field 
identifier foo and then tlie Refactor -> Rename... menu. 
Rename tiie field to myVector. You can use the Preview... 
button to inspect the cascade of changes resulting from ihis- 
e.g., in MyMain, the reference to foo has changed to myVector. 
What's wrong with this picture? Select the myVector field name 
in HatryClass and Refactor -> Encapsulate Field,.. In the 
dialog that appears^ make sure that keep field reference is 
unchecked and click OK. If you now inspect MyMain, you 
should see die field access changed to a method access and 
myVector is now private. Now proud of HairyClass, we rename 
it GreatClass using the same refactoring feature by selecting 
the class name or the class icon in the Package Explorer. Lefs 
go further by creating an interface for it. Select the GreatClass 
name and Refactor -> Extract Interface... Name die interface 
f GreatClass and check off all methods except 
setMyVectof(Vectof). Note tliat GreatClass implements 
IGreatClass. Now let’s be silly and delete getMyVectorQ from 
GreatClass and save. An error appears at the top: click for 
suggestions and ask it to Add unimplemented methods Now 
getMyVectorO is re-instated, with a pointer to the method's 
Javadocs in IGreatClass. For fun, inline the execute method. 

Refactoring is a subject in itself. Explore the refactoring 
features in Eclip.se and you'll see that it is very hard to break 
them. You can rename or move anything, with collateral 
refaaoring of comments and literals as well, if you want. It is fun 
to use the refaaoring dialog's Preview... button to try hits of 
whabifs with yt>ur code. For more on refaaoring, see the help 
system's Java Development User Guide -> Tasks -> Refactoring 

listing 2: HairyClass and JVfyMaiti 

OrijUnaJ listinjis of HairyClass and MyMain. 

Claae HairyClass 
I 

public Vector foo: 
public int count: 

public void execute0 
f 

foo nnw Vgc tor C count); 


Class MyHain 
\ 

public static void inaln{St rin^f] argsj 
I 

HairyClass he ~ new ffairyClassO : 
he.count = 10: 
he.execute(): 

If(he.fuQ.sizet) “ to) 

Syatem. out/pi:iiitln( "Hairy class, but it worked!"): 

1 

) 


Long Distance 



Toll Free (800/888/877/866) service, 
same low per minute rate for incoming calls. 


10 cents per minute calling card. 

Detailed billing directly from Capsule Communications, o Covista Company. 

Quality electronic and telephone customr support. 

No monthly billing fee if you sign up for AUTOPAY billing 
option or if your bill is over $20.00 eoch month. 

fWOrt S/.M fee fs rfiwseif n^en your Hi/K o wider S?0.M for off mn-iaopay n«/aroe«.) 


Straight 6 sewnd biffing increments 


Excellent rotes on intrastate, introlata/toll colls 
and international calling with no term contract. 
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BllLUS 

By default, ihc pn^ject compiles incTementally as you save 
Hies, There are also tools for generating Javad(K:s, JARs, adding 
your own ''externar tools^ and so on. Of coarse, for complex 
projects, the natural Louis are Apache’s Ant or Maven, 

Eclipse has an installed Ant plug-in that provides an Ant 
editor, two views, and a dialog. Both views are outliners: one 
is used to navigate elcmenls in the editor^ the other to quickly 
execute arty target. The Ant dialog lets you configure your 
build and change Ant options. Also, there’s a trend to generate 
Am files rather than execute black-box tools, For example, 
Eclipse’s Javadoc generator (File -> Export -> Javadocs) will 
create an Ant file for you that runs Javadoc with all your 
settings. 'Itiis lets you include the Javadoc (or any other toors) 
Ant output into your main Ant. 

Finally, with Eclipse's A^pedJ IDE plugin, there is supj>ort 
for multiple build configurations, allowing you to, e.g., switch 
between pre-production and production time builds. 

Ritnninc; And Doogging 

Each project can be assigned multiple configurations for 
launching and debugging. The debugger prtjvides all of die 
basic features, including remtrte JVM debugging. This makes 
it easy to work with web appSication servers; and, there are 
IDE plugins for JBoss, Weblogic, Websphere, and Tomcat to 



ctmlrol llie server. For illustrated, step-by-step instructions 
for running and debugging your project, start with Help's 
Java Development User Guide -> Getting Started -> Basic 
Tutorial .section. 

TlvSTINti Ani> QA 

Eclipse's JUnit i)lug-in helps you to set up test cases i>y 
miiigaiing the tedium of manually creating test classes. There are 
wiziirds to create test cases and suites, run them, create test 
configuntiions and delmg tliem. If you are interested in this, 
sLep-by-step instructions are available in the help system's Java 
Development User Guide -> Getting Started -> Basic Tutorial. 

Jb understand liow well your tests cover the possible 
runtime cases, you can instrument your coile with the Clover 
plug-in (hTtp://www.thecortex.net/dover). Clover also gathers 
statistics to analyze your code’s runtime characteristics. 

Finally, Eclipse’s Hyades plug-in is an ambitious project to 
f)rovide a reference standard for tracing, testing and monitoring: 
it implements the lJMh2 Test standard. It includes user interfaces 
for pnifiling, testing (from lest case modeling to 
imfdemeniation), logging, and plaiform-specific data colleaion. 
Hyack^ provides mcKlules for cross-pUitfonn and mulri-platfonn 
developmenL Stable versions of Hyacles are available from the 
Eclipse website. 

T1u\MWORK 

If you are one of those rare individuals in a development 
team, you'll use the Synchronize view or, for a full workbench, 
the CVS Repository Exploring perspective. You can get to ihe 
latter via Window -> Open Perspective -> Other . Set up and 
creation of projects is straightforward Eclipse 2.x supports SSI 11, 
and SSn2 will lie supported in Eclipse 3-0 (in early release at the 
time of thi.s writing), 

CONCXUSION 

Though we've only scratched the surface of the Et lipse IDE, 
by miw you should have an insight into Eclipse, why you might 
watil to use it, and how it fits into the Macintosh universe. Future 
articles will focus on cTo.ss-platform development using Eclipse’s 
JFace and SWT libraries, on Objective C developnient, and on 
more plug-ins. 
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SOFTWARE 



By Dave Wooldridge 


Communicating with Customers 


How the New CAN-SPAM Act Affects 
Software Developers 

Over the last few months, you've Lindoubtedly heard talk of 
the new CAN-8PAM An rhai became federal law in the United 
States on January 1, 20()A. The purpiosc of the CAN-SPAM Act is 
to help regulate and reduce the onslaught of spam that plagues 
all of our inboxes, hut the perceived effectiveness of the new 
law has been met with mixed reactions. Many [)coplc fcx^l tliai 
the law is not strict enough and actually legitimizes unsolicited 
e-mails. Siil! receiving hundreds of spam messages per day> 
touting organ enlargement solutions, get rich quick pyramid 
schemes, generic prescription painkillers and Viagra alternatives? 
You Ye not alone. 

Whether you l^elievc in the validity the CAN-SPAM Act is 
irrelevant. Violations carry a severe penalty. Depending on the 
specific offense, penalties include jail sentences of one to five 
years, plus hefty [Tionetary fines. CAN-SPAM also discusses the 
offering of a bouncy of at least 20% of the collected fines to 
citizens who report violators. And with the strong hatred the 
general public has for spam, you can count on seeing a lot of 
people submitting reports, especially if diey can make money for 
putting spammers i>ehind bars! As a federal law in the LI.S., it 
supercedes any regional state anti-spam legislation that currently 
exists, although some stales may still pursue their own 
prosecution of spam offenders, Needless to say, anti-spam laws 
should not i>e taken lightly. To read the entire CAN SPAM Act in 
its entirety, visit http://wvvw.spamlaws.com/federa 1/108s877.htmI 

For those of you who tmd legal documents to read more 
like alien Klingon scripture tluin actual English can rest easy. 
*riiis month's column will summarize the key points of the CAN- 
SPAM Act and how they directly affect software developers. As a 
programmer communicating with only your existing customers 
and opt-in e-newsletter sui:>scribers, you may wonder why you 
should l>e concerned with this new law, especially since many 
of the rules apply to unsolicited e-mail. The simple truth is that 
people lead busy lives and while they may have voluntarily 
subscTilxid to your e-newsleiter last Octobeq ccjme January they 


may not have any recolleetion of doing so when they receive 
your latest e-mail Tl^ey report it as spam, not rememl)ering they 
actually did subscribe at some point, and then before you know 
it, you’ve got men in black suits with badges knocking on your 
front door. You can never be too careful or conscientious when 
it comes to people’s e-mail privacy. Even if you employ double 
optrin procedures for your e-newsletter and customer mailing 
lists, it is important for you to understand the law. Honor the new 
rules with every bulk e-mail campaign you deliver, so that you 
dcf not accidentally wind op on the wrong side of a lawsuit. Plus, 
for those of you who do maintain a regular e-ncwslcttcr mailing 
list (and if you don’t, you should), we'll explore some effective 
techniques for maintaining your subscriher base, strengthening 
customer loyalty and increitsing software sales. 

The “From’’ Address 

The “FronY line should state your name or your Ijusiness 
name with a valid e-mail address. Never forge a false e-mail 
address and never substitute the name with marketing jargon 
(like ‘‘Special Offers”). 

Besides the fact that it Ls against the law, using a false or 
different e-mail address other than the one you are sending from 
is a sure-fire way to get cauglil by spam filters. For example, you 
decide to send the latest e-newsletter to your mailing list over the 
weekend frcjm home, using your personal DSL account, but you 
want the e-mail to look professional you forge the Trom’’ line 
to be your company e-mail address. While this may seem 
liarmless enough, two problems can arise. One, your ISP’s mail 
server may detect the false “From” header and block the bulk e- 
inaU from being sent. And two, many of the anti-spam filters that 
people use are smart enough to spot false "From" headers and 
automatically send your e-newsleller to die “Junk Mail" folder 
where it gets deleted. You don’t want to spend valuable time and 
money prrxlucing an e-newsletter that never gets read. 

The “Reply-To” Addri-ss 

Always use a "Reply-To" e-mail address that is guaranteed 
to be valid and active for at least thirty (30) days after you send 
ihe e-mail. 


Dave Wooldridge is the founder of Electric Butterfly (www*ebut ter fly * 00111 ), the web design and scjftware company re.sponsible for irelpLogic, 
^Stimulns, Unittelf j, and the popular developer site, RBGarage*ccxn. 
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I"or those recipients who decide they want to unsubscribe, 
they often cio not scroll clown far enough to see the unsubscribe 
iasmiciions at the ix)itom of Ihe message, .st> tficy will click the 
Reply button and e-mail you a request to be removed from the 
list. Manually processing these kinds of unsubscribe requests can 
lx: tedious and time-consuming, s(j an effective way to deal with 
this prol:>lem is to set-up tlie "Reply-To" e-mail address with an 
auto-responder message. Most web hosting providers and ISFs 
support an e-mail auto-responder option, whicfi shoots l>ack a 
pre-defined message to any person who e-mails tliat address. 
Most cx>mpanies use them for notifying clients when specific 
employees are on vacation, etc. hul they can also be used to 
provide customer service to your mailing list subscribers. Set up 
a new e-mail address such as replies@vourcompanyxom that will not 
be used for any other purpose than as your e-newslerter's “Reply- 
To" address. Add an auto-responder message to that e-mail 
account. Tlie message should thank the sender for contacting 
your company and explain politely tliat in order to unsub.scrilx: 
from the mailing list, ihcy sliouid visit the following link (and 
then include the unsubscrilxf URLh It’s also a good idea to list the 


URL or e-mail address for contacting customer support in case the 
sender wanted to ask a question or receive technical assistance 
on one of your .software prtjducls. Make sure your auto- 
rcsix>nder is in plain text format to ensure that even text-only e- 
mail programs can properly display the message. 

The ‘'Subject’^ Line 

Your e-mairs "Subject" line should be descriptive and 
directly related to the content of your mc.ssagc. Using misleading 
or deceptive “Subjea" lines (such as "Your account has been 
declined!" for a home loans promotion) can carry hefty penalties. 

Using vague "Subject" lines may seem like a brilliant ploy to 
gel curious recipients to open your e-mail message, but in 
today's world of sophisticated spam filters and Dver-c:aulious 
risers^ e-mails such as "Check this ciut!" or "Deal tif die Century!” 
will, more often than not, end up unread in the "Junk Mail” 
folder. So not only are they against the law, bur these 
questionable "Subject" lines will not stand out in an already 
ovcTsaturated sea of vague spam headlines. 


BMS 


THE LAW OFFICE OF 
BRADLEY M. SNIDERMAN 



If you're developing software, you need your valuable work protected with 
trademark and copyright registration, as well as 
Non Disclosure Agreements. 


Then, when you are ready to sell it, you can protect yourself further 

with a licensing agreement. 


I am an attorney practicing in Intellectual Property, Business Formations, 
Corporate, Commercial and Contract law. 

Please give me a call or an e-mail. Reasonable fees. 


2 3 67 9 Calabasas Rd. #558 • Calabasas, CA 91302 

PHONE 818-222-0365 FAX KI8-59I-1038 EMAIL b ra d @ sni d e r m a n .com 
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New CodeOulver 1-5 Now AvailabloE 
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tigure L Eien though rectpienL% mluntarily suhscrihed 
lo your opiAn mailing list, Ittki- extra care to efisure that 
your e-mail messages are ejjeciim, while remaining 
compliant with state and federal laws. 


Your goal Ls to create a -subject line that catches the 
attention of recipients while honoring the true content of 
your e-mail message. Including your company name in the 
""Sutjjecl” line may prove effective, hut unless youVe a well- 
known entity like Adobe or Macromedia, people may not 
instantly recognize your name. For small software 
companies and independent shareware developers, the eye¬ 
catching word that will jog users' memories Is most likely 
the name of your product. Using our fictional software 
product, CodeQuiver, as an example, the “Subject" line in 
Figure 1, Item I is “CodeQuiver cNewsletter January 2004.” 
You could obviously make the line longer with additional 
words such as “Electric Butterfly January 2004 eNewsletter: 
CodeQuiver Update,” but you run the risk lliai users' have 
their incoming e-mails listed with a narrow width for the 
“Su]>jecL" field, displaying only the first part of the phrase: 
"Electric Butterfly January 2004 cNewslei...'' By placing the 
identifying word “CodeQuiver" in the beginning of the 
phrase, “CodeQuiver" will always be visible, no matter how^ 
narrow the “Subject" field is set in email programs. Our 
“Subject" line will now prove to be much more eye-catching 
for those users who quickly recognize the product name, 
but not our company name. 

But what if’ your e-newsletter promotes more than one 
software product^ Due to space limitations, you don't want to list 
all your products in the “Subject" line. If you Itave several 
software titles and they cater to different markets (some are 


coasumer-oriented, some arc developer tools, etc.) tlien you 
may want to consider sending out several e-newsletters witlj 
each one targeted to specific subscribers in your mailing list. 
Users of your eonsumer-ljased products may not want to read 
in-depth news alx)ut your develai>er tool offerings. The mo.st 
effective e-newsletters are those that are brief and focused on 
the interests of the recipient. Less Is more. They will remain 
subscTilx^rs as long as the conieni remains useful and is easy it) 
read quickly. 

Apple is a good example of a company that utilizes e- 
ncwsletter targeting. When signing up online to receive e- 
maii news from Apple, you are asked to select the specific e- 
newsletters that interest you (usually represented by a list of 
checkboxes). “Apple cNews" announces the latest updates, 
special offers and user tips for Mac OS X, iLife, and other 
consumer-based Apple products. “Quickl'ime News" 
showcases multimedia authoring, special promotions on 
Final Cut Pro, Final Cut Express, and other QuickTime-based 
software. “New Music Tuesdays" provides the latest music 
news and releases available in Apple’s iTunes Music Store, 
“ADC News" is the official e-newsletter for Apple Developer 
Connection, focusing on Xcode, Cocoa, and third-party 
developer tt>ols. If Apple combined all of these different 
topics into one consolidated new.sletter, it would weaken 
their effectiveness to generate sales. 4'here would be too 
mucli information in one e-mail with much of the conreni 
reaching the wrong people whose interests lie in other areas. 
Let’s say a proud father who creates iMovie videos of his 
daughter's soccer games is interested only in hearing abour 
the latest iLife and QuickTime news. If he received a general, 
“all-in-one" Apple e-newsietier that was packed with lots of 
unrelated articles on Objective-C programming techniques, 
he may grow impatient wading through the contenL just to 
find the information that suits his needs. If he unsubsenbes 
after a few issues, Apple then loses the ability to tell him 
about new products and special offers that he would be 
interested in, losing a potential sale, By subscribing to the 
targeted e-newsletters “Apple eNews" and “QuickTime 
News,” he only receives news related to the topics he wants 
to read about, providing a consistent and reliable line of 
communication from Apple to his e-mail inbox. 

If you don’t liave a way to configure and manage targeted 
groups wirhtfi a single mailing list on your own web server, tl:iere 
are several third-party services such as Microsoft bCentral’s 
ListBuilder (http://www.listbuilder.conn/) which provide these 
advanced features and more. ListBuilder generates a sign-up 
web form that enables subscribers to select their topics of 
interest (which ListBuilder calls “Groups”) from a list that you 
pre-define. ListBuilder hosts your mailing list dauibase and 
aulomafically manages all submissions and unsubscribe 
requests. Using ListBuilder’s convenient web admin tools, you 
can elect to send an e-newsletter to either the entire list or to 
only specifre Groups. 
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E-mah. Identifiers 

If you e-mail an unsolidled message promoting your 
products or services, you must identify the e-mail as an 
advertisement in the ^‘Subject" line. Although there is nt> 
predefined standard, most e-marketers use I he label fADV]. Make 
sure the lalxd is easy to spot by placing it at the Ix^ginning of the 
“Subject field. For example, XodeQiiiver Improves 
Programming Productivity!’' would become “[ADV] CodeK^uiver 
Improves Programming Pioductiviiy!” 

Solicited e-mails that are delivered to opt-in subscribers 
are not required to include any kind of idenLifien but since 
stHTic recipients may accidentally forget that they did 
subscribe voluntarily, you can avoid false .spam accusations 
by politely reminding them in the first paragraph of your 
message. Personalize the e-mail with the recipient’s name 
(Figure 1, Item 2) to show that it's not a generic message, 
but that it’s addressed specifically to them. Then add a brief 
sentence that reminds them liiat they chose to receive your e- 
mails (Figure 1, Item 3). This can be done in a very elegant 
way by mixing the phrase with some dialog that explain.s 
why ii is beneficial for ilicm to ctmlmue receiving the e-mail 
messages. Using the fictional CodeQuiver e-newsletter as an 
example, we accomplished both goals with one sentence by 
saying: “As a subscriber to our Free CodeQuiver mailing list, 
you are eligible for special offers and exclusive online events 
from Electric Butterfly.” 

Any e-maiis (both solicited and unsolicited) iliai include 
sexually oriented material must be labeled as such in the 
“Subject” line. Most software developers won’t have a need 
for this kind of labeling, but ju.sl in case some of you develop 
adult multimedia applications or web sites, it might be 
helpful to note that many adult magazines use the identifier 
INUDITY] in the "Subject” line when e-mailing 
advertisements to their subscribers. Home states in the U.S. 
consider the unsolicited delivery of sexually oriented e-mails 
to be against the law and enforce serious penallie.s, .so it is 
strongly recommended to consult an attorney before sending 
e-maiis with this kind of content. 

Unsubsckibe Requests 

Wiiether you are sending solicited or unsolicited e-mails, 
each and every e-inail is re(|Uired to include an easy to find 
"unsul>scribe" link somewhere in the body of the message. A 
recipient should be able to opt-out from your mailing list in one 
step (of no more than two steps)„ Yoitr opi-out in.strticLions 
should i>c very easy to folkfw, making the process extremely 
simple. Forcing recipients to jum[) through a complicated string 
of steps as a deterrent to keep them from imsnbscrihing is not 
only agaiast the law, hut will only seive to agitate potential 
customers. All unsubscribe reque,s!,s must be honored within ten 
(10) days of receiving them. 

Most e-marketers place the 'Tinsub.scribe” link at the 
bottom of the e-mail message. For opt-in e-newsletters, this 
is a good place to once again remind recipients why they 


are receiving llie e-mail. In Figure 1, Item 6, the 
“unsubscribe" link is accompanied by a brief sentence of 
instructions: “This e-newsletter is only being sent to those 
subscribers who have asked to receive these mailings. To be 
removed from future mailings, click here to unsubscribe”. 
Just in case some recipients do not think to scroll down to 
the holiorn of the message, placing a .second “unsubscribe” 
link near the top of the message provides added 
convenience. A subtle way to do this without cluttering your 
content is shown in Figure 1, Item 3, where the 
“unsubscribe” link is also added to the tail-end of the 
introductory paragraph. This may seem like overkill, but if 
you only include the one “unsubscrilx” link at the very 
bottom, you’ll be surprised by how many e-mails you 
receive from people who cannot figure out how to opt-out. 

Another way to prevent confusion is to provide a 
confirmation page that informs people that their unsubscribe 
reque.si was successful and that they should not receive any 
more mailings from you. If your mailing lisi system requires 
subscribers to 0 [jt-out by replying via e-mail with the word 
“unsubscribe” in the "Hubject” line, use an auto-responder to 
.send an e-mail message hack lo the user, acknowledging 
their recjuesl. 

It Is your responsibility to ensure your automated opt- 
out process is working properly. Double and even Iriple- 
check your opt-out feature. If people are unable to 
successfully unsubscribe from your mailing list, their first 
guess will not be a faulty system. They will asssume die worst: 
that you are trying Lo Lake advantage of their good will. 
Feeling frustrated and exploited, lhe.se potential customers 
just turned into angry enemies who may falsely report you as 
a spammei-. 

A Physical Postai. Address 

All solic ited and unsolicated e-mails are required to include 
the valid postal address of the sender. This means your full street 
address, city, state/province, zip code, and country, ir’.s .standard 
practice to place the postal address at the very bottom of the e- 
mail message, beneath the unsub.scrihe instructions. 

If you are a home-ba.sed shareware developer and would 
rather not give otii your liome address (for fear of custonicrs 
knocking on your front door on a ^SatUIday afternoon), then rent 
11 F.O. box from your Icxal post office or mail supplies .store. 
Prices are very affordable, typically ranging from $40 to $1(K} 
(US) f)er year. Using a P.0, box as your public company address 
will also shield your home residence from receiving junk mail 
from address collectors. 

Guilty By Association 

ihe CAN-HPAM Act also bans automated e-mail harvesting, 
so programming a rolioi .script to crawl web sites to collect e- 
mail addresses is striedy prohibited. This means that pitrchasing 
a list of harvested e-mail addresses from a third-pady^ c ompany 
or utilizing a Imik e-mail service whose database consists of 
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harvested e-mai) addresses is also against the law. 

No\ only are you responsible for your own e-niail 
practices^ hut you are also responsible lor all affiliates^ 
resellers, and inarkeiing agencies who send out e-inuils on 
your behalf. Whether you have directly instructed these 
partners lo prcimote your products/services or if they are 
acting independently in ihe hopes of increasing their own 
commissions, you are ultimately responsible for their actions 
since the e-mails are tied directly to the promotion of your 
software company. This is usually an easy element lo control 
with resellers and marketing firms, but it can become 
staggeringly difficult to manage with an affiliate program, 
hnticing we!> site owmers to promote your software l)y using 
special purchase URLs that track and reward commissions 
based on sale.s they generate can be an extremely powerful 
marketing tool. Affiliate programs like this have proven to 
be incredibly successful for online retailers like 
Ama/.on.com, but managing tiie selling tactics of these 
affiliate members can be somewhat tricky. Since affiliates 
make money when customers buy your software through 
their special affiliate hyperlinks, they often barrage the 
public with web advertisements and unsolicited e-mail 
promotions in the ho(>es of increasing their commissions. To 
enforce that all affiliates obey local and federal spam laws, 
all program members should be required to sign a Terms 
Conditions documcni iliai limil.s your liability and states 
their selling boundaries. Let it be knowm in no uncertain 
terms that any affiliates who violate the rules will luive rlieir 
membership terminated and may face legal repercussions. 

Extra Mfasures 

Beyond the new CAN-SPAM Act, there are several tilings 
you c an do to further safeguard your e-newsietter campaigns 
and make them more efTecrive as a key communication platform 
betw'een you and your SLibs<Tihers. 

rKiuble Opt-iii, Don t let jK“oplc clutter your mailing list 
with invalid e-mail addresses or the unaiiLhori/cti e-mail 
addresses of others. After signing up online, a verification 
mes.sage should .sent to the submilled e-mail address, asking 
the owner to confinn their subscription request l>y t:lickiiig the 
included URL. If the rec|uest was initially made in error, tliey can 
opiout by simply doing noihing. If the .submitted e-mail address 
is invalkh then it won t be added to the mailing list (^since there 
is no one on the receiving end fo confirm the request). Making 
the opr-in path a simple iwtKsiep prtKXfs,s will ensure that your 
subscrilHTS are genuinely interested in receiving your e- 
newsletters. 

Privacy Policy. Every web site and mailing list should 
have a privacy policy. Many people arc so afraid ending 
up on unsolicited spam lists that they refuse to submit their 
e-jiiail address in any online form unless you tell them 
upfront that their e-mail address will never be sold or 
disiribiited to any one outside of your company* On the same 
screen as your e-news wel> form, include a brief sentence 


guaranteeing that you will never si tare their personal 
information and include a URL link to your privacy policy. 
Some c*marketers even include the ''privacy policy" URL at 
the bottom of every e-mail (in llie same paragraph as the 
“unsubsenbe" link). 

Never Use Allachmems. With so many compuler 
viruses being distributed through e-mail, the general public 
has liecome very wary of e-mail attachments. The fear has 
escalated to ilie point where e-mails with attachments that 
were not sent by a friend or family member are usually 
quickly deleted wiihout being opened* If you’re sending an 
HTML e-newsleiLer, never send the H1'ML document as an 
aTTachment - always embed Lite HTML into the main body of 
the e-mail. And never .send the web graphics used in the 
HTML e-newsleiLcT as aUsichmenls. Aside from the fear factor 
of attachments, using relative paths to attached graphics in 
y<iur <IMG> tags does not work properly in some e-mail 
programs, incorrectly displaying your HTML e-newsletier with 
broken images. The professional way to display graphics 
within your HTML e-matls is to host the gra[>liics on your web 
server and then use absolute UI{Ij> in your <1MG> tags* For 
example, instead of using a relative path: 

<imK .W's'lclftfi jpg" tx>iUfl^"0"> 

ustf an absolute path: 

<img \«:=aiap://www.yiwir5iU'.eom/Iogo4pg’’ tKrighl=’'SO'Nifikr^^O''> 

Never Use HTML Forms. Avoid embedding forms in 
your irfML e-mails. Besides the fact that some older e-mail 
programs do not support HTML forms, they tend to scare or 
iniimidule recipients* People are often suspicious of what is 
being activated when the "Submil” button is clicked and 
where their data is being sent. Even if your subscribers tmst 
your company, they may noi trust the e-mail since they have 
no way to prove its auihenltciiy. The last couple years have 
seen hundreds of e-mail scams disguising tiiemselves as eBay 
or PayPal, asking customers to verify their passwords, bank 
account numbers, social security numbers, etc. through e- 
maibbased forms. Not wanting to he I lie next victim, 
subscribers may opt to simply delete the e-mail or wttrse yet, 
unsubscribe. If you want e-mail recipients to participate in an 
online poll or survey, post the HTML form on your web site 
and then promote it in your e-mail with a URL link u> that 
form jiage. 

Useliil Inforniarion. Don't as.sume people will remember 
what your software tloes by only promoting tlie latest release or 
sale price in your e- newsletters* In Figure 1, Item 4, we 
promote the new CodeQuiver release while briefly reminding 
readers of CodeQuiver s primary function. And if your e- 
newsletters only enecjurage software purchases, then dieir 
usefulness may dimmish in the eyes of readers. By providing 
convenient user tips and techniques (Figure 1, Item 5), 
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recipients will be motivated to remain an active subscriber for a 
much longer pericxl of lime. 
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Figure Z Using an e-maii merge program like ImeiliMerge, 
yvu can send fx^rsonalized e-maik to your customer 
mailing list. Sending your e-mail with a miUHiMtri MIME 
type mil allow your message lo display on both 
HTML-enabled and lexl-oniy e-mail programs. 


Personalize. If you deckle noi lo use a mailing list 
service such as Micn>sori bCentrars ListBuilder or custom web 
server software, but elect to e-mail your mailing list frtmi your 
own computer, you should still personalize each e-mail with 
individual name.s and e-rnail addresses (Figure 1, Item 2), 
Personalizing your e-newsletters and customer 
communications adds a nice touch, building a direct bridge 
between you and each recipient. Do not send one message 
With your entire mailing list hidden in the BCC field. Many 
ISPs will refuse delivery, auto-detecling these kinds of bulk e- 
mails as spam, and even if they do get past ISP gateways, most 
personal spam filters will discard them. 1'he best way to send 
out your own e-news let ter Ls by sending il to each recipient 
individually as a .separate, personalized e-niaik Manually, this 
would lake far too much time, but there are several mail 
merge software applications available for die Mac chai can 
help automate this process. I nielli Innovations' IntelliMerge 
(http://www.intetlisw.com/intellimerge/) is one sikU solution. 
Import your mailing list into IntelliMerge and then embed 
special database tags in your e-newsletter's text to dynamically 
populate those tags with the appropriate subscrii)er 
information when e-niailed via InrelliMerge. For example, the 
«Full Name» tag (Figure 2, Hem 1) will be replaced with 
the subscril>er's name wlien IntelliMerge delivers the e-mail 
(Figure 1, Item 2). If you prefer to use Mac OS X\s Mail and 


Address Book, then Christian Fries' SeriaSMail 
(hltp://www.chnstian''ffies.de/osx/SerialMail/) may he a viable 
solution for you. 

Catering to Text-Only E-mail Pn^grams. Due to 

fXTsonal preferences, limited access U> the latest e-mail 
solbvare, and/or the ongoing threat of e-mail-driven viruses, 
some people arc unable to read H'lML e-mails or choose lo 
disable die HTML option. Since these precious few may l>e 
either existing cusk^mers or potential new customers, don't 
exclude them from enioying your e-newsletters. This dtxjstVt 
mean you have to design text-only e-mails lo meet the lowest 
common denominator. Yt)u can configure tlie e-mail with a 
multi-parr MIMH type. This enables one part of the me.ssagc to 
lie designated as HTML, while the other pan is relegated to 
plain text. Setting tlie current message in IntelliMerge as 
Xustom HTML" turns it into a “multi-parC e-mail, displaying 
two fields: one for the HTML version of your c-newsietter and 
one for the plain text version. In HTML-compatible e-mail 
programs, the HTMl. version will automatically display, leaving 
the plain text version liidden. In text-only e-mail programs, the 
plain text version will be displayed by default. If you prefer 
everyone to read the more elegantly designed Ifl'ML version, 
you can post it as a web page on your site and include die URL 
and viewing instructions in the plain text section (Figure 2, 
Item 2), so that text-only recipients can view the HTML e- 
newsletter to their web browsers. 

Stay Informed 

Before sending out bulk e-mails from your own 
computer or web server, review your IS I* or web hosting 
provider's e-mail policies. E-mailing thousands or even 
hundreds of people at one time can set off “red flags" with 
your ISP and web hosting provider. You don't want lo send 
out your latest software announcement and then have your 
account shut clown for violating an existing e-mail policy. 
Internet access providers are becoming increasingly strict in 
un attempt to control and reduce spam. Although you may 
only be delivering an e-ncwsletler to your double opt-in ii.st 
f>f happy, legitimate subscribers, your ISP is not aware of 
these details - all they see are traffic log.s of 3.000 e-mails 
being sent from your account within the short span of a few 
minutes. Using a third-party service like Microsoft (bCentrars 
ListBuilder avoids these kinds of complications. 

Stay on top of the latest Iwal and federal anti-spam 
developments. Even though your opt-in e-newsleuer mailing iist 
would not l^e considered spam, iPs a gmjd idea to be aware of 
atiy new changes or amendments, so that your e-mails are 
always compliant with the law. When in doubt, consult an 
attorney so as to choose the right e-mail strategy that i:>e5t 
protects you and your company. Better safe than sorry in the 
precarious work! of e-mail marketing. 
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Byjono Bacon 



A multupkitform graphical toolkit 


Tim BlRl'H OF THE TOOiJtIT 

In tlic software development world, iJicre are many tools 
and services avaibble to help developers maximise their 
applic'ation development cycle, and squeeze every hit of 
functionality oiil of their products. These tools include 
compilers, debuggers, development environinenLs, profilers, 
and, of course, graphical toolkiis. In this article, 1 will review a 
toolkit that is rapidly growing in reputation and ability; Qt, the 
flagsliip prcxJuti from Norwegian company Trolltech. They state 
that Qt can make the ‘‘CtKle Less. Build More. Compile 
Anywhere" motto a reality. 

In this article T will be reviewing the latest version of Qt 
available at the time of writing, version 3^2,2.1 wil! assume you 
have never used Qt l?efore, and so will evaluate the different 
asj>ecLs of the Ql system. Although I will lx: discussing many 
different features, not all of them are specific to the new 3.2*2 
version; I will discuss specific features in this new version 
towards the end of the article. This way thexse of you familiar 
with Qt can find out what is new in 3-2.2, and those not can gel 
a perspective on the whole Ql tcx>!kii, and its features. 

It's all ARoirr the code 

Qt is a multi-platform lotdkit. '^Nothing new there” 1 hear 
you scream, citing Java as an example, but Qi offers a slightly 
different method of creating graphical applications. First, Qt is a 
native toolkit. Ihis means that when you create a Qt application 
and compile it, a native binary is created lu run on each specific 
operating system. The speed implications for the application are 
therefore drastically improved, and large applications should 
work, tlieoretically, as fast as any otlier native strftware, with the 
added benefits of QFs cross platform source code. 

The acaial cross platfonii nature of Qt is largely a feature of 
its Application Programming Interface (API). The concept here is 
that the source code remains the same for each platform version 
of Qt, so 10 create a binary for another platform, you just 
recompile using the Qt for that platform. Sounds great in theory, 
but does it work? We will investigate this later in the article. 


Before we get onto the cross platfonn nature of Qt, however, let 
us first look at what Qt can do and what is available in it. 

QT FEAlUilliS 

I have been familiar with Qt as a product since the release 
of the first version, and each major release has put more and 
more functionality under the hood. Tlie first and most basic set 
of functionality is for creating graphical interfaces. Ql includes 
widgets (the equivalent of Ctmtrols) for buttons, checkix)xes, 
radio Imitons, tabs, icon panes, canvttses, dialog boxes, and 
other common interface elements. In addition to these elements, 
there are special dialog lx>xcs (such as a file picker, about Ixix, 
etc.) and facilities tliat save die developer from having to re- 
implemefit dic\se functions over and over. 

In addition to diese graphic'al components, Qt includes a 
number of additional features. One of the most critical set of 
features are the convenience classes for handling data and types. 
Qt provides a numlK:^^ of these classes to sup|x>rt Arrays, Strings, 
Vectors, Maps, and many more types. In addition to these bask 
classes there are also classes to handle nelworking, sockets, file 
transfer, sound, and many other aspects of software development. 
It is good to see that Trolliech has created a rich API that not only 
provides graphical widgets, but also provides a number classes 
that make the day to day tasks of programming it a little l)ii easier. 
Another feaaire in Qt is the coneepL of additional modules. These 
extra modules have specific functionality that can Ixi added to the 
API. Ihese modules include a graphical canvas, databa.se access, 
networking, OpenGL, and XML faditiies. 

Aldioogh Ql IS primarily a graphical toolkit and convenience 
classes, Trolltech lias worked to supplement this API wiih uk)Is 
and facilities to assist in die development of projects. These 
additional Lck>Ls include the graphical dialog Ik)x creation tool Qt 
Designer, the translation kkiI Qt Linguist, the documentation itKil 
Qt Assistant, and the compilation t<K)l QMake. We will look at 
each of these tools later in this review. 

Qt Usage 

Ql is a C++ based toolkit, and Object Orientated 
Programming (OOP) is fundamental to using Qt. Each of the 
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components is avjiilablc as a class (such as a QPushBuUon to 
create a push fmtton widget), and each c:lass has a number of 
melhtxis to handle common tasks and features. Although some 
developers use prtKcdura! programming for graphical 
applications, the nature of OOP lends iLseif well to GUI 
programming due to the fact that inheritance is fundamental to 
GUI’s, As an example, liiere is the general concept of a butUm 
(something that you click on), and then specific types of buttons 
(push, radio, toolbar, etc). In Qt, inheritance is used in this way 
so that the general C^Ruiton class is inherited by a more specific 
QPushBuUon class, for example. This process gives the 
developer all the functionality that could l>e needed for that 
specific widget, and the lower level functionality for its inheritetl 
class. This is incredibly flexible and is implemented well in Qt. 

Development of applications can be quite varied in Qt, 
When developers begin programming with a toolkit, they often 
use classes witli a lot of functionality that is rarely used, that 
df>es nothing but increase the size of the !>inary. In Qt things are 
a little different. 'Iliere are different classes that serve different 
uses. As an example, there is a QMa in Window class that 
provides a lot of fiincrionality for typical office type applications 
witli menus, toolbars, and a main content area. Although great 
for this kind of functionality, it may seem a litiie bit of (wcrkill 
for more simplistic applications or graphical eleinenis. Say you 
wanted to create a simple window with a single text box to type 
your password into, you could use a QEJialog class that is much 
more efficient. 

One of the most inierenting features of Qt is the way in 
which user interaction is handled. In many toolkits there is the 
concept of events, messages, call hacks, etc,, where a 
particular widget will start a particular event when the user 
dues something. It is then the programmers responsibility lo 
capture the event and do something con.stmctive in response 
lo it. Trolltech has taken this (often bizarre and complicated) 
concept and refined it, coming up with a solution named 
Signals and Slots, The basic idea ts that each elas,s has a 
number of pre^defined signals llial are emitted when 
something happens, such as clicking on a button or selecting 
an item in a menu. 

For example, the QPushButton class that is used to create 
a simple push button (.siiefi as an OK and Cancel button in a 
dialog box) has a clickedO signal; this signal is emitted when 
somexme clicks on the button. This particular signal can then 
be connected to a slot, which is any normal function. Using 
this system, you can easily connect any function to a user 
interaction. It requires only a single line of code to perform 
this connection, 

ADomoNAi. limis 

Earlier I mentioned that there are some tools included with 
Qt that can assist in developing your applications. These tools 
come in the form of Qt Designer, LinguLst, A,ssisLant, and QMake. 
All of these tools are genuinely useful, and speed up 
development with Qt. 


Qt Designer 

Qt Designer essentially gives you the a[)ility to draw your 
gnit>hical interface visually by dropping interface elements onto 
a window. Qt Designer is a very flexible tool, and has suppon 
for all of the graphical widgets that are available in the toolkit. 
Not only can you add items sucfi as buttons, checkboxes, radio 
buttons, scrollbars, textboxes, etc., but you can also add menus, 
and their items. Adding the components to your application 
window is as simple as selecting the widget from the toolbar and 
then drawing it. Qt Designer does not stop there in terms of 
creating your interface, It also gives you the ability to define 
your .signal/slot connections. Thi.s procedure is started by 
selecting the object that will eiiiii tlie signal, then entering the 
name of the slot that (lie signal connects to. 

When an interface has been created and the file is saved, Qi 
Designer will store your inierface in a .ui file that is comprised of 
special XML ctxle. It is a wise move {)n the part of Trolllcch to use 
an open standard such as XML for their file foniiat as the ui files 
can then be lepurpased for other usc.s such as XSl traasformatitms 
to possibly link Qt Designer interfaces with web pages. 

When die file is saved, a special tool called moc can be run 
on the file to convert it to the relevant C++ header and 
implementation file. Once llie source ctxle has been genemied, 
you will have a Ixjtlerplate class for the interface available that 
can be used by re-implementing tlic class in your main axle. 
You need to use polymorphism to use the class due lo the fact 
I ha! any rntdiftcalions made to the generated class will be lost 
when you next generate the tiass. Using this method of re¬ 
implementing the chess, you can then use the generated class 
and define your own slots of the same function name. Tliis is a 
clever technique, and while a little confusing at first, gives the 
develoiXfr ultimate flexibility. 

Qi linguist 

Qt Linguist is a hmiI For creating translations within Qt 
applications. The idea l>ehind the tool is that you .separate those 
who code the application from ihose who cjx^ate translations. 
Tile traditional methtx] of supfiorting multiple languages when 
ileveloping softwaa- has lieen to implement multiple translations 
either within the code, or via a text file for each language. Qt 
prefers the more elegant teehnic|ue of creating so called 
tramlation Jtias that are createtl by the translators with Qt 
LinguisL Those files are then madt,‘ use of by the developers in 
the Qt application. I like this ledinique Ixxause noi only is it 
simple, but this kind of simplicity means that Qi ticveloj>ers can 
not only create multi-platform applicaiion.s, hut multi-platform, 
multi-language applications. I am .sure that non-rechnical 
translators will apprec iate this simplified method of dealing with 
translations, as well. 

QMake 

The final tool in the Qt toolbox (1 will cover Ql Assistant 
in the next section) is QMake. This .simple Utile tool leLs you 
handle the building your applications easily. Many 
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developers spread their code oui over muliiple source files, 
and LradiLionally developers have needed Lo edit Makefiles, 
and other build scripts, to get their applicaiions to build. 
When you roll in the mulii-platform nature of Qt with 
different compilers and build environments, this could get 
real challenging real fast, QMake seeks to simplify the 
process, and when run will generate a make file for building 
y(Hir application. 1 have some experience with the GNU tools 
to do this, such as automake, and QMake is a welcome 
change. I found QMake not only makes the build system 
seamless, but due to the fact that it is bundled with Qt, 
makes it even easier. 

E>ociimi:ini AnoN ani> Qfv AssistAiNX 
Otic of the major strengths of Ql is its incredible 
ciocii mentation. As a developer, documentation is always 
something that is importani to have available due to the fact that 
every intimate derail of the API may need to be used, and as 
such should lx‘ well documented. Luckily, the Qt documentation 
U.‘am have done an incTcdilile job at not only creating an 
iiiipre.ssive reference manuai for every minute detail of the API, 
but have also included a numlier of other features in the 
documentation, lliese include: 

Qt Commumiy 

Information alx)ut mailing lists, newsletters, bug reporting 
and more. 

Getting siaried 

Details on how to l^egin prf>gmmming with Qt, This 
section also includes two full ttitoriafs, and many 
examples. 
zl/V Reference 

A full and complete reference of every class, function, 
and definition in the Qt tcK>lkiL The reference is concise, 
and easy to n?ad. 


Moduies 

Dck’u mentation, tucorials, and examples of each of the 
additional modules within Qt. 

Ouewietvs 

This section provides a numlK.T of walkthrough, and 
discussion documents on various parts of the Ql toolkit, 
such as the Qt object modal, and signals and slots. 

Porting and pla forms 

This section gives information, and details on supporting 
each of the different platforms for your f>rojecl, 
compilation details, anrl specific platform notes. 

Tooh 

Tliis section pn)vides documentation for each of the tools 
included with Qt, such as Qt Designer, Qt Linguist, Qt 
Assistant, and QMake. 

Licenses and credits 

This section provides information about the different 
licen.se,s available with Qt. 

The documentation available with Qt is in HTML format, 
and can be viewed in any web browser (as well as being 
available at http://doc.trolltech.com). Although a web browser 
sufTices for basic viewing of the dociimeniation, Qt includes 
a special tool for dealing with tlie documentation called Qt 
Assistant. Ql As.sistant provides an interface for searching, and 
querying the documenialion, and viewing it. Altliough a 
.simple front-end to the documcniatitm, Qt Assistant provides 
a more integrated method of reading the class 
reference/inforination instead of a web browser I am 
impressed that Trolltech takes dcKumentaiion this seriously, 
and have committed to not only providing good 
documentation, but a tool to access it. 



Now serving Cocoa® 
just the way you want it. 

Training for fi/iac OS X doesn’t have to be the same did flavor. 
Reserve your seat in a class at our scenic lodge locatbn, 
or have experts come to you for Extreme Mentoring. 
Two weeks of on-site instruction and collaboration, 
customized to the requirements of your project. 
Book now for 2003. See why we’re different. 


c 



Bia 

ncrD 

ranOH 


Intensive Classes for Programmers 
www.bignerdranch.cora 


Marcji 2004 • MAcdTitCH 


Q. 


77 














In use 

Qt is a powerfyl toolkit, and has been carefully developed. 
When using the toolkit, you always get a taie feeling tjf quality 
with what you are doing. This is laigely from tlie tried and tested 
development model that has been created by Trolltech. Using 
C++ for graphical development is a natural choice due to its OOP 
philosophy, and it is very rare that yoti are in a position where 
you can see no elegant way of doing soinetliing. The available 
number of classes in Qt is impressive, and there is a convenience 
class for most common processes involved with modern software 
development. Not only do tlie classes aOow you to create 
functionality easily, but each class has a rich API, consisting of a 
number of metliods that are useful tn most situations. 

Qt Designer is an integral pan of the Qt system, and 
generally works well for most applications. A few releases back 
Qt Designer was considerably more primitive titan it is these 
days, and the latest version of Qt Designer is quite a mature and 
useful tool. While not a fully RAD tool (in the sense that it docs 
not aaively generate code that is embedded directly in your 
project), it is about as RAD as yt>u want it to be - it generates 
the code, and yim put it imu your project, 'I bis prevenLs the 
kinds of spaglietti code prcjblems that arc often associated with 
RAD ux)ls. 

Although it is p<)ssit>le to review and evaluate Qt in a sierilc 
environment where only Qt is used, in the rtfal world Qt faces 
stiff comfietition from the like.s of Java^ CcKoa, GTK, and others. 
Prom my experience, Qt stands up well to these competitors, 
and offers a compelling, and in many cases, superior prtxJuci. 
The main areas that many developers seem to look at when 
evaluating a produa is its ease of use, functionality, and stability. 
Prom my testing, Ql seems to stand up on all of these points and 
I cannot really think of many areas in which Qt would be 
unsuitable for development. One lesUtinenl to the nature of Qt, 
in my opinitm, is the extent to which it i.s used. Because of the 
dual liceasing of the toolkit, and the availability of a GPL 
version, Qt has been used by the UNIX based KDP project 
(www.kde.org). The sheer scope of that project is a go^^d 
demonstration of the ability of Qt as a toolkit. KDE can be 
installed on Mac OS X using the Fink system (fink.sourceforge.net)* 

New in 3*2,2 

Qt has implemenied a number of new features, in 
addition to the already im]>ressive set of the 5A release* These 
new features include: 

Netv Splmhscreen clans 

This new class provides a conremporary spiashscreen 
class that can be used to show a splash screen while your 
program is loading. The class will also allow you to 
display status messages in the splash screen* 

New toolbox widget 

A new widget has been added to create a toolbox that 
has t:<>llapsil>le areas, llie widget was originally used in 
Qt Designer, and not available as a common class. Now 


it is, and can be added using the Qt Designer interface. 
Improved menu editor in Ql Designer 
ITie menu editor in Qt Designer has always worked Pine, 
but not worked as intuitively as you might liave expeaed. 

It has been revamped in 3.22. 

Ihread it)cal storage 

Multi-tlireaded applications can be written in Qt, and a 
new class has been added to store thread variables 
between threads. 

Injml masks 

Input masks for controlling wiiat input is added to a text 
entry box has Ixicn added. This makes it easier to validate 
user input* 

Improved SQL support 

With the addition of a DB2 driver, there has l)een a 
revamp of die SQL support in Qt, and data aware widgets 
work better with queries now. 

Impromd indie and syriac support 

Support for right to left languages has Ik^co improved. 

with full support for indie and syriac languages. 

Impnnmd prinlerseiup diatog 

Additional functionality has btfen added to the printer 
setup dialog* 

There was also a long list of user and developer submitted 
!>ugs that were fixed with this release, and various changes to 
particular platform versions of Qt* 

CONtllJSION 

Qt is a great icKilkit, I am impressed with the technical 
stnjcture of the software, the feature set, and the documentation 
lhal is included. Qt seems to offer a nice combination of hard 
core power, anti RAD development. C++ is a good choice fora 
language to base the toolkit on, although it would i>e nice to see 
bindings for Java, or jxissibly even PHR The toolkit not only 
provides a gfxxl range of graphical components, but also 
provides high perfomiance data handling cla.sses, and nice 
additions, such as data aware dalalrase widgets and classes, 
OpenGL supptm, and other features* The addition of Qt 
Assistant, Qt Linguist, and particularly Qt De.signer, are sensible 
choices by Trolltech. Qt Designer, in panictilar, rapidly increases 
development speed* 

If you arc^ looking for a Rxjlkit where you can write your 
code once, and run it on a numlier of different platforms, Ql is 
well worth looking in lo. In these days of Windows, Linux, and 
Mac OS X, using a toolkit such as Qt makes sense. It makes 
pariicuhir sense for those developers creating free clients, and 
software to give away, as the GPL edition provides ec|uivalent 
functionality to the commercial version, wnih only a change in 
licensing. The commercial version licensing allows you to 
distribute closed source applications commercially* 

1 look forward to seeing how Trolltech will expand Qt in 
the future, and look forward to seeing more Qt applications 
running on all my computers. 
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Coming in April! 


Upgrading to Panther? 

Let Peachpit help you make an easy 
transition to Apple's newest operating 
system. Our wide selection of titles 
caters to every learning level and 
style so you're sure to find just the 
book to tame your Mac's inner beast. 


Mac OS X Conversion Kit 9 to 10 
Side-by-Side, Panther Edition 
By Scott Kelby 
0-7357-1389-8 • $29.99 


Mac OS X Panther Killer Tips 

By Scott Kelby 
0-7357-1393-6 • $29.99 


Mac OS X 10.3 Panther; Visual 
QukkStart Guide 
By Maria Langer 
0-321-21351-3 • $24.99 


Mac OS X Panther Hands-On Training 
By Garrick Chow 
0-321-24171-1 • $35.00 


Mac OS X Security 

By Bruce Potter, Preston Norvell and 

Brian Wotring 

0-7357-1348-0 • $39.99 


Robin Williams Mac OS X Book, 
Panther Edition 
By Robin Williams 
0-321-23296-8 • $29.99 


Save 30%! 


fliilBrs 


Buy these books today at www.peachpit.com/mactech0204 and save 
30“/o off their retail price, plus enjoy free domestic U.S. shipping. Just 
enter coupon code EM-F4AA-MTMF when you get to our checkout 
page. It's that easy!' 
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■ Common API across all platforms and hardware 

■ Hardware-based code and data encryption 

■ Field-upgradable and reusable hardware 

■ The most cost-effective network licensing solution available 

■ The only system to employ RID/RED and AXAN security 

■ Engineered and manufactured to exacting ISO9001 standards 


Test the 


f Protection Kit 


The Key 


www.griftech.coiii 

'j'U'wmiifibu.com 

-^- 

Protection Kits also available at ^ 
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Pear Revolution 

You just 

aeVt^m 
VW0h you tvone 

Missing you t 


SKS 5 ^"« 


Revolution 2.1: the English like language 
designed around the way you think. 

Develop and deliver on 14 platforms, including Mac OS X, Windows and Linux. 
Now with support for XML, additional SQL databases, video capture, Unicode, 
Reports, enhanced faceless CGI applications,and more. 

And now from Dan Shafer, the first "how to" book on Revolution. 

Get a headstart with "Revolution: Software at the Speed of Thought", 
volume one now shipping from www.runrev.com/revpress. 

Thousands of developers have already joined the Revolution. Can you afford to wait? 
Pricing starts at $149. Don't let the revolution in coding start without you. 

User Centric Development Tools 


Revolution 

Studio 
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Runtime Revolution • 91 Hanover Street • Edinburgh EH2 IDJ • UK 
Phone +44 (0)131 718 4333 * Fax +44 (0) 845 4588487 • www.runrev.com * Email info@runrev.com 
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